home *** CD-ROM | disk | FTP | other *** search
/ Night Owl 6 / Night Owl's Shareware - PDSI-006 - Night Owl Corp (1990).iso / 007a / pv050doc.zip / PVRAY.DOC < prev    next >
Text File  |  1991-09-08  |  151KB  |  3,754 lines
  1.      Persistence of Vision Raytracer (PV-Ray)
  2.           Version 0.5 BETA
  3.      ------------------------------------------------
  4.      PV-Ray is based on DKBTrace 2.12 by David Buck
  5.  
  6. 9/8/91
  7.  
  8.  
  9. This program is freely distributable.  The authors retain the
  10. copyright to the program but authorize free distribution by BBS'es,
  11. networks, magnetic media, etc.  The distributor may charge
  12. no more than five dollars ($5) U.S. for this software. 
  13.  
  14. The images and data files generated by the raytracer are the
  15. property of the user of the software and may be used for any
  16. purpose without restriction. 
  17.  
  18. The authors make no guarantees or warranties with this program and
  19. claims no responsibility for any damage or loss of time caused by
  20. this program. Bug reports may be sent to the authors but the
  21. authors are under no obligation to provide bug fixes, features, or
  22. any support for this software. 
  23.  
  24. We would also like to place the following conditions on the use of
  25. this  program:
  26.  
  27.  1) That it should not be used as part of any commercial package
  28. without the explicit written consent of the PV-Team.
  29.  2) if you create any interesting pictures, please send them to us. 
  30.  3) If you make any changes to the source code, please let us know.
  31. That's the way this program was built!
  32.  4) This text file must accompany the program.
  33.  
  34. PvRay headquarters are on CompuServe's Comart forum Raytracing
  35. section. We meet there to share info and graphics and discuss
  36. raytracing, fractals and other kinds of computer art. Comart is
  37. also the home of the Stone Soup Group, developers of Fractint, a
  38. popular IBM-PC fractal program. Everyone is welcome to join in on
  39. the action on CIS Comart. Hope to see you there!
  40.  
  41. AAC:  As of July of 1990, there is a Ray-Trace specific BBS in the
  42. (708) Area Code (Chicago suburbia) for all you Traceaholics out
  43. there.  The phone number of this new BBS is (708) 358-5611.  I am
  44. Co-Sysop of that board, and it is  filled with interesting stuff.
  45. And now, back to the DOCS... 
  46.  
  47. The GIF file reader was written by Steven A. Bennett.  Here's his
  48. copyright notice:
  49.  
  50.     * DECODER.C - An LZW decoder for GIF
  51.     * Copyright (C) 1987, by Steven A. Bennett
  52.     *
  53.     * Permission is given by the author to freely redistribute and 
  54.     * include this code in any program as long as this credit is  
  55.     * given where due.     
  56.     * In accordance with the above, I want to credit Steve Wilhite, 
  57.     * who wrote the code which this is heavily inspired by...
  58.     *
  59.     * GIF and 'Graphics Interchange Format' are trademarks (tm) of 
  60.     * Compuserve, Incorporated, an H&R Block Company.
  61.  
  62. The Noise and DNoise functions (used for texturing) were written by
  63. Robert Skinner and used here with his permission. 
  64.  
  65.  
  66.  
  67. This manual is divided into the following sections:
  68.  
  69.    1) Program Description
  70.    2) Program History and Information
  71.    3) Getting Started
  72.    4) Command Line Parameters
  73.    5) A Tutorial Walkthrough
  74.    6) The Scene Description Language
  75.    7) Displaying the Images
  76.    8) DKB/PV-Ray Utilities
  77.    9) How it All Works (or How to Get What You Want)
  78.   10) Common Questions and Answers
  79.   11) Converting Data Files from Versions Prior to 2.10
  80.   12) Handy Hints
  81.   13) Compiling the Code
  82.   14) Porting to Different Platforms
  83.   15) References
  84.   16) Concluding Remarks
  85.  
  86. Some sample worlds and their corresponding images are provided with
  87. this distribution in the file PVDAT.ZIP.  Many people, have created
  88. some really spectacular images.  Looking at the data files for
  89. these will give you some ideas and help you design your own data
  90. files.
  91.  
  92.  
  93.  
  94.  
  95. 1)  Program Description
  96.  
  97.  
  98. This program is a ray tracer written completely in C.  It supports
  99. arbitrary quadric surfaces (spheres, ellipsoids, cones, cylinders,
  100. planes, etc.), constructive solid geometry, and various shading
  101. models (reflection, refraction, marble, wood, and many others).  It
  102. also has special-case code to handle spheres, planes, triangles,
  103. and smooth triangles.  By using these special primitives, the
  104. rendering can be done much more quickly than by using the more
  105. general quadrics.  In order to create pictures with this program,
  106. you must describe the objects in the world.  This description is a
  107. text file called "<filename>.data", and <filename> defaults to
  108. "object" if not specified.  Normally, such files are difficult to
  109. write and to read. In order to make this task easier, the program
  110. contains a parser to read the data file.  It allows the user to
  111. easily create complex worlds from simple components.  Since the
  112. parser allows include files, the user may put the object
  113. descriptions into different files and combine them all into one
  114. final image. 
  115.  
  116.  
  117.  
  118. 2)  Program History and Information
  119.  
  120.  
  121. DKB Version 1.2:
  122.     Initial Amiga release.
  123.  
  124. DKB Version 2.0:
  125.     First release Version 2.0 Conversion to the IBM done by Aaron
  126. A. Collins.  New textures, Specular and Phong highlighting added by
  127. Aaron A. Collins.  Triangle, Smooth Triangle, Sphere, Plane support
  128. added by David Buck. RAW, IFF and GIF image mapping added by David
  129. Buck and Aaron Collins. Transparency and Fog added by David Buck
  130.  GIF format file reader by Steve Bennett (used with permission)   
  131.  New Noise and DNoise functions by Robert Skinner (used with
  132. permission) TARGA format output file capability added by Aaron A.
  133. Collins  ANSI-C function prototyping for ALL functions,
  134.     Reversal of the order of writing screen data from the original
  135. DKB/QRT "RAW" file format.
  136.     For IBM's, it has a crude VGA 320x200 by 256 color display
  137. rendering ability.
  138.  
  139.     Version 2.0 compiles under Turbo-C 2.0 on the IBM P.C. and
  140. Lattice C 5.05 on the Amiga.  The only file which contains the ANSI
  141. extensions is dkbproto.h, so for non-ANSI compilers, you only need
  142. to remove the declaration of the parameters in the config.h file
  143. and the whole thing should compile.  There are several example
  144. config.h files for Amiga, IBM, and Unix.  The appropriate one
  145. should be copied over CONFIG.H, and the MAKEFILE should be edited
  146. for your particular system and compiler configuration before
  147. compilation. 
  148.     
  149.     Version 2.0 has a significant difference from prior releases: 
  150. Speed!  The new primitives of SPHERE, PLANE, TRIANGLE, etc. greatly
  151. speed up  tracing.  Another significant speed-up is that world X-Y-
  152. Z values beyond 10 Million or so are ignored, and ray tracing
  153. beyond that distance will cease.  This produces 2 minor
  154. peculiarities:
  155.  
  156.      1)   A black stripe at the horizon point of Pre-2.0 scene
  157. description .data files that have "ground" and "sky" planes
  158. defined.  The planes were traced out to a much greater "infinity"
  159. so this effect was unnoticeable, prior to version 2.0.
  160.  
  161.      2)   Tiny black pixels in the texture, or "Surface Acne".
  162.  
  163.     This is usually caused by rays being refracted or reflected
  164. such that  the ray does not happen to hit any object, and
  165. eventually becomes black in color as it gets too far away and gets
  166. clipped.  This effect can be minimized by enclosing the scene with
  167. distant "walls", "floors", or placing "ocean floors" beneath water,
  168. etc.  So far, no scenes have required placing such planes behind
  169. the camera, unless an "environment map" of sorts is desired.  See
  170. SKYTEST.DAT for several examples of spurious distant planes.  If
  171. your "acne" still doesn't go away, it may be due to a large pixel
  172. sample area and it's accidentally picking a point which is just
  173. inside the primitive being hit.  This is a more tricky problem to
  174. solve, and anti-aliasing the image will definitely help if this
  175. sort of thing occurs. 
  176. DKB Version 2.10:
  177.     A few unofficial releases were made between 2.01 and 2.10.  The
  178. following  points capture the major changes:
  179.  
  180.     - Less memory is required for image mapped GIF and IFF files. 
  181.     - The output format command-line option was changed to +fx    
  182.       where 'x' denotes the output format.
  183.     - The display option +d now takes an optional extra character 
  184.       +dx  where 'x' is system-dependent.  This allows you to     
  185.       specify the graphics mode by a command-line switch.
  186.     - The tokenizing pass has been removed.  It's now called      
  187.       directly by the parser.
  188.     - The environment variable PVOPT is used in addition to the   
  189.       pvray.def file and the command-line options.
  190.     - The numbers in the data file can now use full scientific    
  191.       notation  eg. 10.23e-4
  192.     - The +c option was added to continue an aborted trace.     
  193.     - You can now colour or texture each component of the CSG's   
  194.       separately.     
  195.     - Layered textures implemented (see the section on textures). 
  196.     - When using GIF and IFF images for image mapping, you can now 
  197.       indicate that specified registers are partially or completely 
  198.       transparent.     
  199.     - Textures are now transformed whenever the object or shape   
  200.       they are attached to are transformed.
  201.     - The texture CHECKER_TEXTURE has been added.
  202.     - All keywords relating to the appearance of the surface have 
  203.       been made illegal in an object definition unless they are   
  204.       inside a TEXTURE block.
  205.     - The "basicshapes.data" file has been split up into          
  206.       shapes.dat, colors.dat, and textures.dat.  These files have 
  207.       also been expanded with more useful declarations.
  208.     - The -l command-line parameter has been added to support     
  209.       library directories.
  210. DKB Version 2.11:
  211.     - Quartic surfaces (4th order) added by Alexander Enzmann.    
  212.     - Parser now accepts ^Z as a whitespace
  213.     - Keyword END_SMOOTH_TRIANGLE added (previously, END_TRIANGLE 
  214.       was used.)
  215. DKB Version 2.12:
  216.     - Bug in smooth triangles fixed to allow them to be scaled and 
  217.      translated.     
  218.     - METALLIC texture added.
  219.     
  220. Persistence of Vision Raytracer - PV-Ray
  221.  
  222. PV-Ray Version 0.5 BETA:
  223.     - See whatsnew.txt & PVRAY05.doc
  224.  
  225. 3)  Getting Started
  226.  
  227. If you've been reading this document diligently until now, you'll
  228. probably want to go in and display some images to see what the
  229. raytracer does. Here's what you need to do:
  230.  
  231.    1) Put the file "sunset.dat" into your current directory.      
  232.       (sunset.dat is in PVDOC.ZIP)
  233.    2) Make sure the files "colors.dat", "shapes.dat", and "       
  234.       "textures.dat" are present.
  235.    3) Set up the default parameters.  This can be done by creating 
  236.       a file called "pvray.def" or by setting the PVOPT environment 
  237.       variable. In either case, use the following line (you may   
  238.       change these defaults to suit your system):
  239.  
  240.       Amiga: -w320 -h400 -v +f +d +p +x -a
  241.       IBM:   -w320 -h200 -v +f +d +p +x -a
  242.  
  243.       Meaning:
  244.       -v - Don't be verbose, i.e. don't show line numbers during
  245. trace.   
  246.       +f - Write an output file in "dump" or "Targa" format
  247. (machine specific; IBM default is "Targa", Amiga default is "dump". 
  248.       +d - Display the image while rendering (on some systems, an 
  249.            additional character may follow this option to specify 
  250.            the graphics mode to use for the display).
  251.          -w320 - Make the image 320 pixels wide.
  252.          -h400/200 - Make the image 400 or 200 pixels high.
  253.          +p - Prompt before exitting to let you look at the       
  254.              picture. 
  255.          +x - Allow exitting with a key hit before the trace is   
  256.              finished.  
  257.          -a - Don't Antialias (Antialiasing smooths out jagged    
  258.              edges and takes longer to do).
  259.  
  260.    4) To render a scene, type:
  261.  
  262.          pvray -isunset.dat -osunset.dis
  263.            ^
  264.            |_____ See note below*
  265.  
  266.       
  267.          * On different systems, the name of the executable may   
  268.            vary. Check to see what it is on your system.  
  269.         
  270.          -isunset.dat
  271.             - Read the input file "sunset.dat"
  272.          -osunset.dis or -osunset.tga
  273.            - Call the output file "sunset.dis" this is the usual  
  274.              file name extension for "dump" format.  "Targa" format 
  275.              files (default for IBM's) generally use the extension 
  276.              ".tga".
  277.  
  278.    5) Once the image has been rendered, you must use a post-
  279. processor to  create the final viewable image file (i.e. an IFF or
  280. GIF file), unless you possess 24-bit display hardware and can view
  281. the generated output files directly.  The post-processor used
  282. depends on your system.  See the section "Displaying the Images"
  283. for more details on post-processing the image.
  284.  
  285. The following section gives a detailed description of the command-
  286. line options.
  287.  
  288.  
  289.  
  290. 4)  Command Line Parameters
  291.  
  292. This program is designed to be run from a command line.  The
  293. command-line parameters may be specified in any order.  Repeated
  294. parameters overwrite the previous values.  Parameters may also be
  295. specified in a file called "pvray.def" or by the environment
  296. variable "PVOPT".
  297.  
  298.      -wxxx     Width of the picture in pixels
  299.      -hxxx     Height of the picture in pixels
  300.      +v        Verbose option - Display image stats while tracing. 
  301.      -v        Disable verbose option
  302.      +f[x]     Produce an output file
  303.      -f        Don't produce an output file
  304.                If the +f option is used, the ray tracer will      
  305.                produce an output file of the picture.  This output 
  306.                file describes each pixel with 24 bits.  Currently, 
  307.                three formats of output files are supported:
  308.  
  309.                   +fd (default) - Dump format (QRT-style)         
  310.                   +fr  - Raw format - three files for R, G and B. 
  311.                   +ft - Uncompressed Targa-24 format (IBM)
  312.  
  313.  
  314.                Normally, a post-processor is required to create the 
  315.                final finished image from the data file.  See the  
  316.                section on "Displaying the Images" for details.
  317.  
  318.  
  319.      +d[x]     Display the picture while tracing
  320.      -d        Don't display the picture while tracing
  321.  
  322.               If the +d option is used, then the picture will be  
  323.               displayed while the program performs the ray tracing. 
  324.               On most systems, this picture is not as good as the 
  325.               one created by the post-processor because it does not 
  326.               try to make optimum choices for the colour registers.
  327.  
  328.                Depending on the system, a letter may follow the +d 
  329.               option to specify the graphics mode to use.
  330.  
  331.                   All systems:
  332.                     +d      Default Format (same as +d0)
  333.  
  334.                   Amiga:
  335.                     +d0     Ham format
  336.                     +dE     Ham-E format
  337.  
  338.                   IBM:
  339.                     +d0     Autodetect (S)VGA type
  340.                     +d1     Standard VGA 320x200
  341.                     +d2     Simulated SVGA 360x480
  342.                     +d3     Tseng Labs 3000 SVGA 640x480
  343.                     +d4     Tseng Labs 4000 SVGA 640x480
  344.                     +d5     AT&T VDC600 SVGA 640x400
  345.                     +d6     Oak Technologies SVGA 640x480
  346.                     +d7     Video 7 SVGA 640x480
  347.                     +d8     Video 7 Vega (Cirrus) VGA 360x480     
  348.                     +d9     Paradise SVGA 640x480
  349.                     +dA     Ahead Systems Ver. A SVGA 640x480     
  350.                     +dB     Ahead Systems Ver. B SVGA 640x480     
  351.                     +dC     Chips & Technologies SVGA 640x480     
  352.                     +dD     ATI SGVA 640x480
  353.                     +dE     Everex SVGA 640x480
  354.                     +dF     Trident SVGA 640x480
  355.                     +dG     VESA Standard SVGA Adapter 640x480
  356.  
  357.  
  358.      +p        Wait for prompt (IBM: beep and pause) before       
  359.                quitting      
  360.      -p        Finish without waiting
  361.  
  362.                The +p option makes the program wait for a carriage 
  363.                return before exitting (and closing the graphics   
  364.                screen).  This gives  you time to admire the final 
  365.                picture onscreen before clearing it. 
  366.  
  367.  
  368.   -ifilename   Set the input filename
  369.   -ofilename   Set output filename
  370.  
  371.                If your input file is not "Object.dat", then you can 
  372.                use -i to set the filename.  The default output    
  373.                filename will be "data.dis" for dump mode,         
  374.                "data.red", "data.grn" or "data.blu" for raw mode, 
  375.                and "data.tga" for Targa mode.  If you want a      
  376.                different output file name, use the -o option.
  377.  
  378.                (on IBM's, the default extensions for raw mode are 
  379.                ".r8", ".g8", and ".b8" to conform to PICLAB's "raw" 
  380.                format).
  381.  
  382.      +a[xxx]   Anti-alias - xxx is an optional tolerance level    
  383.               (default 0.3) 
  384.      -a        Don't anti-alias
  385.  
  386.                The +a option enables adaptive anti-aliasing.  The 
  387.                number after the +a option determines the threshold 
  388.                for the anti-aliasing.  If the colour of a pixel   
  389.                differs from its neighbor (to the left or above) by 
  390.                more than the threshold, then the pixel is         
  391.                subdivided and super-sampled.
  392.  
  393.                If the anti-aliasing threshold is 0.0, then every  
  394.                pixel is  supersampled.  If the threshold is 1.0,  
  395.                then no anti-aliasing is done.  Good values seem to 
  396.                be around 0.2 to 0.4.
  397.  
  398.                The super-samples are jittered to introduce noise  
  399.                and make the  pictures look better.  Note that the 
  400.                jittering "noise" is non-random and repeatable in  
  401.                nature, based on an object's 3-D orientation in    
  402.                space.  Thus, it's okay to use anti-aliasing for   
  403.                animation sequences, as the anti-aliased pixels    
  404.                won't vary and flicker annoyingly from frame to    
  405.                frame.
  406.            
  407.      +x        Allow early exit by hitting any key (IBM-PC only)  
  408.      -x        Lock in trace until finished        (IBM-PC only)
  409.  
  410.                On the IBM, the -x option disables the ability to  
  411.                abort the trace by hitting a key.  If you are      
  412.                unusually clumsy or have CATS that stomp on your   
  413.                keyboard (like I do - AAC :-)), you may want to use 
  414.                it. If you are writing a file, the system          
  415.                will recognize ^C at the end of line if the system 
  416.                "BREAK" is "ON".  If you aren't writing a file, you 
  417.                won't be able to abort the trace until it's done.
  418.  
  419.                This option was meant for big, long late-nite traces 
  420.                that take ALL night (or longer!), and you don't want 
  421.                them interrupted by  anything less important than a 
  422.                natural disaster such as hurricane, fire, flood,   
  423.                famine, etc.
  424.  
  425.      -bxxx     Use an output file buffer of xxx kilobytes.
  426.                (if 0, flush the file on every line - this is the  
  427.                default)
  428.  
  429.                The -b option allows you to assign large buffers to 
  430.                the output file.  This reduces the amount of time  
  431.                spent writing to the disk and prevents unnecessary 
  432.                wear (especially for floppies). If this parameter is 
  433.                zero, then as each scanline is finished, the line is 
  434.                written to the file and the file is flushed.  On   
  435.                most systems, this operation insures that the file 
  436.                is written to the disk so that in the event of a   
  437.                system crash or other catastrophic event, at least 
  438.                part of the picture has been stored properly on    
  439.                disk.
  440.  
  441.      +c        Continue Rendering
  442.  
  443.                If, for some reason, you abort a raytrace while it's 
  444.                in progress or if you used the -exxx option (below) 
  445.                to end the raytrace prematurely, you can use the +c 
  446.                option to continue the raytrace when you get back to 
  447.                it. This option reads in the previously generated  
  448.               output file, displays the image to date on the      
  449.               screen, then proceeds with the raytracing.  In many 
  450.               cases, this feature can save you a lot of rendering 
  451.               time when things go wrong.
  452.  
  453.                (If you want to impress your friends with the speed 
  454.               of your computer, take an image you've already      
  455.               rendered and use +c in the command-line.  It renders 
  456.               REALLY fast that way!  :-)
  457.  
  458.      -sxxx     Start tracing at line number xxx.
  459.      -exxx     End tracing at line number xxx.
  460.  
  461.                The -s option allows you to start rendering an image 
  462.               starting from a specific scan line.  This is useful 
  463.               for rendering part of a scene to see what it looks  
  464.               like without having to render the entire scene from 
  465.               the top.  Alternatively, you can render groups of   
  466.               scanlines on different systems and concatenate them 
  467.               later.  WARNING: If you are merging output files from 
  468.               different systems, make sure that the random number 
  469.               generators are the same.  If not, the textures from 
  470.               one will not blend in with the textures from the    
  471.               other.  There is an example of a standard  ANSI "C" 
  472.               random number generator in the file IBM.C.  Cut it  
  473.               out and paste it into your machine-specific .C file 
  474.               if you plan to try "distributed processing" and are 
  475.               not sure if you need this standardization.
  476.  
  477.                The -s option has no effect when continuing a      
  478.               raytrace using the +c option.  The renderer will    
  479.               figure out where to restart.
  480.  
  481.      -qx       Rendering quality
  482.  
  483.                The -q option allows you to specify the image      
  484.                rendering quality, for quickly rendering images for 
  485.                testing.  The parameter can range from 0 to 9.  The 
  486.                values correspond to the following quality levels:
  487.  
  488.                0,1  Just show colours.  Ambient lighting only.    
  489.                2,3  Show Diffuse and Ambient light
  490.                4,5  Render shadows
  491.                6,7  Create surface textures
  492.                8,9  Compute reflected, refracted, and transmitted 
  493.                     rays.
  494.  
  495.                The default is -q9 (maximum quality) if not        
  496.                specified.
  497.  
  498.                You may specify the default parameters by modifying 
  499.                the file "pvray.def" which contains the parameters 
  500.                in the above format. This filename contains a      
  501.                complete command line as though you had typed it in, 
  502.               and is processed before any options supplied        
  503.               on the command line are recognized.
  504.  
  505.  
  506.      -lpath    The -l option may be used to specify a "library"   
  507.                pathname to look into for data files to include or 
  508.                for images.  Up to 10 -l options may be used to    
  509.                specify a search path.  The home (current) directory 
  510.                will be searched first followed by the indicated   
  511.                library directories in order.
  512.  
  513.      +z        The +z option is an undocumented feature.  You will 
  514.                not see any references to it in this or any other  
  515.                documentation file for PV-Ray.  In fact, no other  
  516.                section of the document will even admit that it was 
  517.                mentioned here. If you really want to know what it 
  518.                does, then you will have to look into the source   
  519.                code (pvray.c) and read the comment just above the 
  520.                +z option that says "Turn on debugging print       
  521.                 statements."  The full purpose of this option will, 
  522.                therefore, be left as an exercise for the reader,  
  523.                but believe me - it's nothing terribly exciting.
  524.  
  525.                (For those people who run the raytracer on super-  
  526.                fast systems  and want to slow it down, you may try 
  527.                this option. :-)
  528.  
  529.  
  530.  
  531. 5)  A Tutorial Walkthrough
  532.  
  533.  
  534. This section, is designed to get you up and running designing your
  535. own pictures without all the nit-picky details.  Once you've made
  536. a few of your own data files, you'll probably want to advance to
  537. the next section to fill in the gaps.
  538.  
  539. 5.1)    The First Image
  540.  
  541. Let's get right to the meat of the matter and create the data file
  542. for a simple picture.  Since raytracers thrive on spheres, that's
  543. what we'll render first.
  544.  
  545. First we have to create a viewpoint to tell the computer where our
  546. camera is and where it's looking.  To do this, we use 3D
  547. coordinates.  The usual coordinate system for PV-Ray has Y pointing
  548. up, X pointing to the right, and Z pointing into the screen as
  549. follows:
  550.  
  551.  
  552.                 ^Y
  553.                 |
  554.                 |   /Z
  555.                 |  /
  556.                 | /
  557.                 |/       X
  558.                 |-------->
  559.  
  560.  
  561.  
  562. Using your personal favorite text editor (i.e., user interface),
  563. create a file called "picture1.dat".  Now, type in the following
  564. (note:  The input is case sensitive, so be sure to get capital and
  565. lowercase letters correct):
  566.  
  567.       INCLUDE "colors.dat"
  568.       INCLUDE "shapes.dat"
  569.       INCLUDE "textures.dat"
  570.  
  571.       VIEW_POINT
  572.          LOCATION  <0 0 0>
  573.          DIRECTION <0 0 1>
  574.          UP        <0 1 0>
  575.          RIGHT     <1.33333 0 0>
  576.       END_VIEW_POINT
  577.  
  578.  
  579. The first INCLUDE statement reads in definitions for various useful
  580. colours. (Being a proud Canadian, I spell colour the proper way
  581. with a "u".  To avoid confusing the rest of the world, however,
  582. I've set up the raytracer to allow either spelling of the word.)
  583.  
  584. The second and third include statements read in some useful shapes
  585. and textures respectively.  When you get a chance, have a look
  586. through them to see but a few of the many possible shapes and
  587. textures available.
  588.  
  589. Include files may be nested, if you like.  The total pre-defined
  590. number of INCLUDE'd files (nested or not) per scene is 10.
  591.  
  592. Filenames specified in the INCLUDE statements will be searched for
  593. in the home (current) directory first, and if not found, will then
  594. be searched for in directories specified by any "-l" (library path)
  595. options active.  This would facilitate keeping all your "include"
  596. (.inc) files, shapes.dat, colors.dat, and textures.dat in an
  597. "include" subdirectory, and giving an "-l" option on the command
  598. line to where your library of include files are.
  599.  
  600.  
  601. This viewpoint declaration puts our camera at the center of the
  602. universe (LOCATION <0 0 0>) pointing into the Z direction
  603. (DIRECTION <0 0 1>) and with the camera being held upright (UP <0
  604. 1 0>).  The final term compensates for the aspect ratio of the
  605. screen (RIGHT <1.33333 0 0>).  If your computer has square pixels,
  606. you may want to change this to "RIGHT <1.0 0 0>".  For details on
  607. exactly how the camera works, see the section "How it All Works". 
  608.  
  609.  
  610. Now, let's place a red sphere into the world:
  611.  
  612.       OBJECT
  613.          SPHERE <0 0 3> 1 END_SPHERE
  614.          TEXTURE
  615.             COLOUR Red
  616.          END_TEXTURE
  617.       END_OBJECT
  618.  
  619. This sphere is 3 units away from the camera and has a radius of 1. 
  620. Note that any parameter that changes the appearance of the surface
  621. (as opposed to the shape of the surface) is called a texture
  622. parameter and MUST be placed into a TEXTURE-END_TEXTURE block.  In
  623. this case, we are just setting the colour.
  624.  
  625. One more detail - we need a light source:
  626.  
  627.       OBJECT
  628.          SPHERE <0 0 0> 1 END_SPHERE
  629.          TEXTURE
  630.             COLOUR White
  631.          END_TEXTURE
  632.          TRANSLATE <2 4 -3>     {This is 2 units to our right, 4
  633. units above,}                                 {and 3 units behind
  634. our camera.}          LIGHT_SOURCE
  635.          COLOUR White
  636.       END_OBJECT
  637.  
  638. (Note:  For light sources, ALWAYS declare them to be centered at
  639. the origin <0 0 0>, then use TRANSLATE to put them where you want. 
  640. If you don't do this, the light source won't work right. We must
  641. also specify the colour of the light source OUTSIDE the TEXTURE
  642. block because the renderer doesn't want to work out the whole
  643. surface colour just to get the colour of the light it emits.)
  644.  
  645. That's it!  Close the file and render a small picture of it:
  646.  
  647.       Amiga: pvray -w80 -h100 -f -ipicture1.dat
  648.  
  649.       IBM & others : pvray -w80 -h50 -f -ipicture1.dat
  650.  
  651.  
  652. 5.2)    Phong Highlights
  653.  
  654. You've now rendered your first picture.  I know you want to run out
  655. and show all your friends how amazing your computer is to be able
  656. to generate such an incredible picture, but just wait a few minutes
  657. - you ain't seen nothin' yet. (For those people who complained that
  658. the picture took too long to draw, just wait - you ain't seen
  659. nothin' yet, either...)
  660.  
  661. Let's add a nice little specular highlight (shiny spot) to the
  662. sphere.  It gives it that neat "computer graphics" look.  Change
  663. the definition of the sphere to this:
  664.  
  665.       OBJECT
  666.          SPHERE <0 0 3> 1 END_SPHERE
  667.          TEXTURE
  668.             COLOUR Red
  669.             PHONG 1.0
  670.          END_TEXTURE
  671.       END_OBJECT
  672.  
  673. Now render this.  In all seriousness, the PHONG highlight does add
  674. a lot of credibility to the picture.  You'll probably want to use
  675. it in many of your pictures.
  676.  
  677. 5.3)    Textures
  678.  
  679. One of the really nice features of this raytracer is its
  680. sophisticated textures.  Change the definition of our sphere to the
  681. following and then re-render it:
  682.  
  683.       OBJECT
  684.          SPHERE <0 0 3> 1 END_SPHERE
  685.          TEXTURE
  686.             Dark_Wood
  687.             SCALE <0.2 0.2 0.2>
  688.             PHONG 1.0
  689.          END_TEXTURE
  690.       END_OBJECT
  691.  
  692.  
  693. The textures are set up by default to give you one "feature" across
  694. a sphere of radius 1.0.  A "feature" is roughly defined as a colour
  695. transition.  For example, a wood texture would have one band on a
  696. sphere of radius 1.0.  By scaling the wood by <0.2 0.2 0.2>, we
  697. shrink the texture to give us about five bands. Please note that
  698. this is not a hard and fast rule.  It's only meant to give you a
  699. rough idea for the scale to use for a texture.  Don't start
  700. reporting problems if you get three bands instead of five.  This
  701. rule of thumb just puts you in the ballpark.
  702.  
  703. One note about the SCALE operation.  You can magnify or shrink
  704. along each direction separately.  The first term tells how much to
  705. magnify or shrink in the left-right direction.  The second term
  706. controls the up-down direction and the third term controls the
  707. front-back direction.
  708.  
  709. I encourage you to look through the "textures.dat" file to see what
  710. textures are defined there and try them out.  Some of them are
  711. quite spectacular.
  712.  
  713. 5.4)    Other Shapes
  714.  
  715. So far, we've just defined spheres.  There are several other kinds
  716. of shapes that can be rendered by PV-Ray.  Let's try one out with
  717. a computer graphics standard - a checkered floor.  Add the
  718. following object to your .dat file:
  719.  
  720.       OBJECT
  721.          PLANE <0.0 1.0 0.0> -1.0 END_PLANE
  722.          TEXTURE
  723.             CHECKER
  724.                COLOUR RED 1.0
  725.                COLOUR BLUE 1.0
  726.          END_TEXTURE
  727.       END_OBJECT
  728.  
  729.  
  730. The object defined here is an infinite plane.  The vector <0.0 1.0
  731. 0.0> is the surface normal of the plane (i.e., if you where
  732. standing on the surface, the normal points straight up.)  The
  733. number afterward is the distance that the plane is displaced along
  734. the normal - in this case, we move the floor down one unit so that
  735. the sphere (radius 1) is resting on it.  The checker texture
  736. specifies the two colours to use in the checker pattern.
  737.  
  738. Looking at the floor, you'll notice that the wooden ball casts a
  739. shadow on the floor.  Shadows are calculated accurately (well,
  740. almost - more later) by the raytracer.
  741.  
  742.  
  743. Another kind of shape you can use is called a quadric surface.  To
  744. be totally honest, the shapes you've been using so far have been
  745. quadrics.  Spheres and planes are types of quadric surfaces.  There
  746. are many other quadric surfaces however.  These are all described
  747. by a certain kind of mathematical formula (see the section on
  748. Quadrics in the next chapter).  They include cylinders, cones,
  749. paraboloids (like a satellite dish), hyperboloids (saddle-shaped)
  750. and ellipsoids as well as the spheres and planes we've used so far.
  751.  
  752. All quadrics except for ellipsoids and spheres are infinite in at
  753. least one direction.  For example, a cylinder has no top or bottom
  754. - it goes to infinity at each end.  Quadrics all have one common
  755. feature - if you draw any straight line through a quadric, it will
  756. hit the surface at most twice.  A torus (donut), for example, is
  757. not a quadric since a line can hit the surface up to four times
  758. going through.
  759. Enough talk - let's render one of these "quadrics"...  While we're
  760. at it, we'll add a few features to the surface.  Add the following
  761. definition to your .dat file:
  762.  
  763.       OBJECT
  764.          QUADRIC Cylinder_Y END_QUADRIC
  765.          TEXTURE
  766.             COLOUR GREEN 0.5
  767.             REFLECTION 0.5
  768.          END_TEXTURE
  769.          SCALE <0.4  0.4  0.4>
  770.          TRANSLATE <2 0 5>
  771.       END_OBJECT
  772.  
  773.  
  774. This object is a cylinder along the Y (up-down) axis.  It's green
  775. in colour and has a mirrored surface (hence the reflection of 0.5)
  776. this means that half the light coming from the sphere is reflected
  777. from other objects in the room. A reflection of 1.0 is a perfect
  778. mirror.
  779.  
  780. The object has been shrunk by scaling it by <0.4 0.4 0.4>.  Note
  781. that since the cylinder is infinite along the Y axis, the middle
  782. term is kind of pointless.  One four tenths of infinity is still
  783. infinity.  (Don't use 0, though.  That will definitely cause a
  784. fatal crash!)  Finally, the cylinder has been moved back and to the
  785. right so you can see it more clearly.
  786.  
  787. 5.5)    Constructive Solid Geometry
  788.  
  789. The shapes we've talked about so far are nice, but not terribly
  790. useful on their own for making realistic scenes.  It's hard to make
  791. interesting objects when you're limited to spheres, infinite
  792. cylinders, infinite planes, and so forth.  
  793.  
  794. Constructive Solid Geometry (CSG) is a technique for taking these
  795. simple building blocks and combining them together.  You can use a
  796. cylinder to bore a hole through a sphere.  You can use planes to
  797. cap cylinders and turn them into flat circular disks (that are no
  798. longer infinite).
  799.  
  800. Before getting into CSG, however, let me talk about inside and
  801. outside.  Every primitive (except triangles - I'll talk about this
  802. later) divides the world into two regions.  One region is inside
  803. the surface and one is outside.  So, given any point in space, you
  804. can say it's either inside or outside any particular primitive
  805. object (well, it could be exactly on the surface, but usually
  806. numerical inaccuracies will put it to one side or the other).  Even
  807. planes have an inside and an outside.  By definition, the surface
  808. normal of the plane points towards the outside of the plane.  (For
  809. a simple floor, for example, the space above the floor is "outside"
  810. and the space below the floor is "inside".  For simple floors this
  811. in unimportant, but for planes as parts of CSG's it becomes much
  812. more important).
  813. CSG uses the concepts of inside and outside to combine shapes
  814. together.  Take the following situation:
  815.  
  816. Note: The diagrams shown here demonstrate the concepts in 2D and
  817. are indended       only as an analogy to the 3D case.  Note that
  818. the triangles supported by       PV-Ray cannot be used in CSG
  819. (except for unions) since they have no       inside and outside.
  820.  
  821.   * = Shape A
  822.   % = Shape B
  823.  
  824.                      *  0
  825.                     * *    %
  826.                    *   *  % %
  827.                   *     *%   %
  828.                  *  1   %*    %
  829.                 *      %  * 2  %
  830.                *      % 3  *    %
  831.               *******%*******    %
  832.                     %             %
  833.                    %%%%%%%%%%%%%%%%%
  834.  
  835.  
  836. There are three CSG operations you can use:
  837.  
  838.    1) UNION A B END_UNION
  839.         A point is inside the union if it is inside A OR it's
  840. inside B         (or both).  This gives an "additive" effect to the
  841. component         objects:
  842.  
  843.                      *
  844.                     * *    %
  845.                    *   *  % %
  846.                   *     *%   %
  847.                  *  1       2 %
  848.                 *       3      %
  849.                *                %
  850.               *******%           %
  851.                     %             %
  852.                    %%%%%%%%%%%%%%%%%
  853.  
  854.  
  855.    2) INTERSECTION A B END_INTERSECTION
  856.         A point is inside the intersection if it's inside both A
  857. AND B.  This         "logical AND's" the shapes and gets the common
  858. part, most useful for         "clipping" infinite shapes off, etc:
  859.  
  860.  
  861.                         %*
  862.                        %  *
  863.                       % 3  *
  864.                      %*******
  865.  
  866.    3) DIFFERENCE A B END_DIFFERENCE
  867.         A point is inside the difference if it's inside A but not
  868. inside B.         The results is a "subtraction" of the 2nd shape
  869. from the first shape:
  870.  
  871.  
  872.                      *
  873.                     * *
  874.                    *   *
  875.                   *     *
  876.                  *  1   %
  877.                 *      %
  878.                *      %
  879.               *******%
  880.  
  881. Let's give a concrete example by drilling a yellow hole through our
  882. sphere. Go to the definition of the sphere and change it to read
  883. the following:
  884.  
  885.  
  886.       OBJECT
  887.          DIFFERENCE
  888.             SPHERE <0 0 3> 1 END_SPHERE
  889.             QUADRIC
  890.                Cylinder_Z
  891.                SCALE <0.2 0.2 0.2>
  892.                COLOUR Yellow
  893.             END_QUADRIC
  894.          END_DIFFERENCE
  895.          TEXTURE
  896.             Dark_Wood
  897.             SCALE <0.2 0.2 0.2>
  898.             PHONG 1.0
  899.          END_TEXTURE
  900.       END_OBJECT
  901.  
  902. One more point about CSG operations.  You can flip a shape inside-
  903. out by putting the keyword INVERSE into the shape's definition. 
  904. This keyword will not change the appearance of the shape unless
  905. you're using CSG.  In the case of CSG, it gives you more
  906. flexibility.  For example:
  907.  
  908.    INTERSECTION B A-INVERSE END_INTERSECTION
  909.  
  910.                    
  911.                            %
  912.                           % %
  913.                          %   %
  914.                          *    %
  915.                           * 2  %
  916.                            *    %
  917.                      %*******    %
  918.                     %             %
  919.                    %%%%%%%%%%%%%%%%%
  920.  
  921. (Note that a DIFFERENCE is really just an INTERSECTION of one shape
  922. with the INVERSE of another.  This happens to be how DIFFERENCE is
  923. actually implemented in the code.)
  924.  
  925. 5.6)    Advanced Textures
  926.  
  927. The textures available in PV-Ray are 3D solid textures.  This means
  928. that the texture defines a colour for any 3D point in space.  Just
  929. like a real block of marble or wood, there is colour all through
  930. the block - you just can't see it until you carve away the wood or
  931. marble that's in the way.  Similarly, with a 3D solid texture, you
  932. don't see all the colours in the texture - you only see the colours
  933. that happen to be visible at the surface of the object.
  934.  
  935. As you've already seen, you can scale, translate, and rotate
  936. textures.  In fact, you could make an animation in which the
  937. objects stay still and the textures translate and rotate through
  938. the object.  The effect would be like watching a time-lapse film of
  939. a cloudy sky - the clouds would not only move, but they would also
  940. change shape smoothly.
  941.  
  942. Often, textures are perturbed by noise.  This "turbulence" distorts
  943. the texture so it doesn't look quite so perfect.  Try changing the
  944. sphere in the above example to have the following texture:
  945.  
  946.          TEXTURE
  947.             Dark_Wood
  948.             TURBULENCE 0.0
  949.             SCALE <0.2 0.2 0.2>
  950.             PHONG 1.0
  951.          END_TEXTURE
  952.  
  953. When you compare this with the original image, you'll see that the
  954. pattern is much more boring.
  955.  
  956. Finally, many textures use colour maps.  A colour map translates a
  957. number between 0.0 and 1.0 into a colour.  The number typically
  958. represents the distance into a vein of colour - the further into
  959. the vein you get, the more the colour changes.  Here's a typical
  960. colour map.  Try this out on the sphere defined above by changing
  961. the definition to this:
  962.  
  963.  
  964.       OBJECT
  965.          SPHERE <0 0 3> 1 END_SPHERE
  966.          TEXTURE
  967.             WOOD
  968.             SCALE <0.2 0.2 0.2>
  969.             COLOUR_MAP
  970.                 [0.0 0.3  COLOUR Red   COLOUR Green]
  971.                 [0.3 0.6  COLOUR Green COLOUR Blue]
  972.                 [0.6 1.01 COLOUR Blue  COLOUR Red]
  973.             END_COLOUR_MAP
  974.             PHONG 1.0
  975.          END_TEXTURE
  976.       END_OBJECT
  977.  
  978.  
  979. This means that as the texture enters into a vein of wood, it
  980. changes colour smoothly from red to green, from green to blue, and
  981. from blue to red again. As it leaves the vein, the transition
  982. occurs in reverse.  (Since there is no turbulence on the wood by
  983. default, the veins of colour should show up quite well.)
  984.  
  985. You can get more "bang for your buck" from textures by using ALPHA
  986. properties of colour.  Every colour you define in PV-Ray is a
  987. combination of red, green, blue and alpha.  The red, green and blue
  988. are simple enough.  The alpha determines how transparent that
  989. colour is.  A colour with an alpha of 1.0 is totally transparent. 
  990. A colour with an alpha of 0.0 is totally opaque.  Here's a neat
  991. texture to try:
  992.  
  993.  
  994.    TEXTURE
  995.       TURBULENCE 0.5
  996.       BOZO
  997.       COLOUR_MAP
  998.           { transparent to transparent }
  999.           [0.0 0.6   COLOUR RED 1.0 GREEN 1.0 BLUE 1.0 ALPHA 1.0  
  1000.                    COLOUR RED 1.0 GREEN 1.0 BLUE 1.0 ALPHA 1.0]
  1001.  
  1002.           { transparent to white }
  1003.           [0.6 0.8   COLOUR RED 1.0 GREEN 1.0 BLUE 1.0 ALPHA 1.0  
  1004.                    COLOUR RED 1.0 GREEN 1.0 BLUE 1.0]
  1005.  
  1006.           { white to grey }
  1007.           [0.8 1.001 COLOUR RED 1.0 GREEN 1.0 BLUE 1.0
  1008.                      COLOUR RED 0.8 GREEN 0.8 BLUE 0.8]
  1009.       END_COLOUR_MAP
  1010.       SCALE <0.4  0.08  0.4>
  1011.    END_TEXTURE
  1012.  
  1013. This is my (famous) cloud texture.  It creates white clouds with
  1014. grey linings. The texture is transparent in the places where the
  1015. clouds disappear so you can see through it to the objects that are
  1016. behind.
  1017.  
  1018. Now for one more feature which is new for 2.10 (hold onto your
  1019. hats!)  You can now layer textures one on top of another to create
  1020. more sophisticated textures. For example, suppose I want a wood-
  1021. coloured cloudy texture.  What I do is put the wood texture down
  1022. first followed by my cloud texture.  Wherever the cloud texture is
  1023. transparent, the wood texture shows through.  Change your sphere to
  1024. the following and you'll see.
  1025.  
  1026.  
  1027.       OBJECT
  1028.          SPHERE <0 0 3> 1 END_SPHERE
  1029.          TEXTURE        { This is the wood texture we used earlier.
  1030. }             Dark_Wood
  1031.             TURBULENCE 0.0
  1032.             SCALE <0.2 0.2 0.2>
  1033.             PHONG 1.0
  1034.          END_TEXTURE
  1035.          TEXTURE { This is the cloud texture we just defined. }   
  1036.          TURBULENCE 0.5
  1037.           BOZO
  1038.           COLOUR_MAP
  1039.           { transparent to transparent }
  1040.            [0.0 0.6  COLOUR RED 1.0 GREEN 1.0 BLUE 1.0 ALPHA 1.0  
  1041.                      COLOUR RED 1.0 GREEN 1.0 BLUE 1.0 ALPHA 1.0] 
  1042.      
  1043.                 { transparent to white }
  1044.            [0.6 0.8   COLOUR RED 1.0 GREEN 1.0 BLUE 1.0 ALPHA 1.0 
  1045.                       COLOUR RED 1.0 GREEN 1.0 BLUE 1.0]          
  1046.            { white to grey }
  1047.            [0.8 1.001 COLOUR RED 1.0 GREEN 1.0 BLUE 1.0           
  1048.                      COLOUR RED 0.8 GREEN 0.8 BLUE 0.8]           
  1049.             END_COLOUR_MAP
  1050.             SCALE <0.4  0.08  0.4>
  1051.          END_TEXTURE
  1052.       END_OBJECT
  1053.  
  1054. Each successive texture is layered on top of the previous textures. 
  1055. In the places where you can see through the upper texture, you see
  1056. through to the lower textures.
  1057.  
  1058.  
  1059. 5.7)    Walk-through Wrap-up
  1060.  
  1061. In this walk-through, I've only tried to show the highlights of the
  1062. raytracer without getting into all possible options and features. 
  1063. To get all of those, you'll have to read through the following
  1064. section on the Object Description Language.  Hopefully it will be
  1065. fairly straight forward now that you have a feel for the language
  1066. and how it works.  Hopefully you'll find that the textual interface
  1067. provided by PV-Ray isn't quite as scary as people think at first.
  1068.  
  1069.  
  1070.  
  1071. 6)  The Scene Description Language
  1072.  
  1073. The Scene Description Language allows the user to describe the
  1074. world in a readable and convenient way.
  1075.  
  1076. The language delimits comments by the left and right braces ({ and
  1077. }). Nested comments are allowed, but no sane person uses them
  1078. anyway, right?      
  1079. The language allows include files to be specified by placing the
  1080. line:
  1081.  
  1082.     INCLUDE "filename"
  1083.  
  1084. at any point in the input file (Include files may be nested).  The
  1085. filename must be enclosed in double quotes and may be up to 40
  1086. characters long, including the two double-quote (") characters. 
  1087. You may have at most 10 INCLUDE'd files per scene trace, whether
  1088. nested or not.
  1089.  
  1090.  
  1091.  
  1092. 6.1)    The Basic Data Types
  1093.  
  1094.      There are several basic types of data:
  1095.  
  1096. 6.1.1)  Float
  1097. Floats are represented by an optional sign (-), some digits, an
  1098. optional decimal point, and more digits. This version supports the
  1099. "e" notation for exponents.  The following are valid floats:
  1100.  
  1101.      1.0  -2.0  -4  34  3.4e6 2e-5
  1102.  
  1103. 6.1.2)  Vector
  1104. Vectors are arrays of three floats.  They are bracketed by angle
  1105. brackets ( < and > ), and the three terms usually represent x, y,
  1106. and z.  For example:
  1107.  
  1108.      < 1.0  3.2  -5.4578 >
  1109.  
  1110. Vectors typically refer to relative points.  For example, the
  1111. vector:
  1112.  
  1113.      <1 2 3>
  1114.  
  1115. means the point that's 1 unit to the right, 2 units up, and 3 units
  1116. in front. "Of what?" you ask?  Well, usually it's relative to the
  1117. center of the "universe" at <0 0 0>.
  1118.  
  1119. In a few places here and there, vectors are used as a convenient
  1120. notation but don't represent a point in space. This is the case for
  1121. the transformations TRANSLATE, ROTATE, and SCALE.
  1122.  
  1123.    TRANSLATE <x y z>       - move the object x units to the right, 
  1124.                             y units up, and z units away from us.
  1125.  
  1126.    SCALE     <xs ys zs>    - scale the object by xs units in the  
  1127.                              left/right direction, ys units in the 
  1128.                              up/down direction and zs units in the 
  1129.                              front/back direction.
  1130.  
  1131.    ROTATE    <xr yr zr>    - rotate the object xr degrees about the 
  1132.                              X axis, then yr degrees about the Y  
  1133.                              axis, then zr degrees about the Z    
  1134.                              axis.  (note that the order matters)
  1135.  
  1136. To work out the rotation directions, you must perform the famous
  1137. "Computer Graphics Aerobics" exercise.  Hold up your left hand. 
  1138. point your thumb in the positive direction of the axis you want to
  1139. rotate about.  Your fingers will curl in the positive direction of
  1140. rotation.  This is the famous "left-hand coordinate system".  If
  1141. you want to use a right-hand system, as some CAD systems do, the
  1142. RIGHT vector in the VIEW_POINT needs to be changed.  See the
  1143. detailed description of the VIEW_POINT, and use your right hand for
  1144. the "Aerobics".
  1145.                        _
  1146.                      _| |_  _
  1147.                    _| | | |/ \
  1148.                   | | | | |  |
  1149.                   | | | | |  V
  1150.                   | | | | |   
  1151.                   | | | | |
  1152.                   |       \____
  1153.                   |         ___|
  1154.                   \        /
  1155.                    |      /
  1156. 6.1.3)  Colour
  1157.  
  1158. A colour consists of a red component, a green component, a blue
  1159. component, and possibly an alpha component.  All four components
  1160. are floats in the range 0.0 to 1.0.  The syntax for Colours is the
  1161. word "COLOUR" followed by any or all of the RED, GREEN, BLUE or
  1162. ALPHA components in any order.
  1163.  
  1164. For example:
  1165.  
  1166.      COLOUR  RED 1.0  GREEN 1.0  BLUE 1.0
  1167.      COLOUR  BLUE 0.56
  1168.      COLOUR  GREEN 0.45 RED 0.3 BLUE 0.1 ALPHA 0.3
  1169.  
  1170. Alpha is a transparency indicator.  If an object's colour contains
  1171. some transparency, then you can see through it.  If Alpha is 0.0,
  1172. the object is totally opaque.  If it is 1.0, it is totally
  1173. transparent.
  1174.  
  1175. For those people who spell "Colour" the American way as "Color",
  1176. the program will also accept "COLOR" as equivalent to "COLOUR" in
  1177. all instances.
  1178.  
  1179.  
  1180. 6.1.4)  Colour Maps
  1181.  
  1182. For wood, marble, spotted, agate, granite, and gradient texturing,
  1183. the user may specify arbitrary colours to use for the texture. 
  1184. This is done by a colour map or "colour spline".  When the object
  1185. is being textured, a number between 0.0 and 1.0 is generated which
  1186. is then used to form the colour of the point.  A Colour map
  1187. specifies the mapping used to change these numbers into colours. 
  1188. The syntax is as follows:
  1189.  
  1190.      COLOUR_MAP
  1191.           [start_value end_value colour1 colour2]
  1192.           [start_value end_value colour1 colour2]
  1193.           ...
  1194.      END_COLOUR_MAP
  1195.  
  1196. The numeric value between 0.0 and 1.0 is located in the colour map
  1197. and the final colour is calculated by a linear interpolation (a
  1198. smooth blending) between the two colours in the located range.
  1199.  
  1200.  
  1201. 6.2)    The More Complex Data Types
  1202.  
  1203. 6.2.1)  Declare
  1204.  
  1205. The data types used to describe the objects in the world are a bit
  1206. more difficult to describe.  To make this task easier, the program
  1207. allows users to describe these types in two ways.  The first way is
  1208. to define it from first principles specifying all of the required
  1209. parameters.  The second way allows the user to define an object as
  1210. a modification of another object (the other object is usually
  1211. defined from first principles but is much simpler).  Here's how it
  1212. works:
  1213.  
  1214. You can use the term DECLARE to declare a type of object with a
  1215. certain description.  The object is not included in the world but
  1216. is made known to the program that it can be used as a "prototype"
  1217. for defining other objects by the name given, as this basic example
  1218. shows:
  1219.  
  1220.      DECLARE QSphere = QUADRIC { First Principles definition of a
  1221. sphere }  <1.0 1.0 1.0>
  1222.           <0.0 0.0 0.0>
  1223.           <0.0 0.0 0.0>
  1224.           -1.0
  1225.      END_QUADRIC
  1226.  
  1227. To then reference the declaration elsewhere in your source file or
  1228. in another included one, and to actually include the object in the
  1229. world, you would define the object using the DECLARE'd object's
  1230. name, like this:
  1231.  
  1232.      OBJECT
  1233.           QUADRIC Sphere
  1234.                SCALE <20.0 20.0 20.0>
  1235.           END_QUADRIC
  1236.           TEXTURE
  1237.              COLOUR White
  1238.              AMBIENT 0.2
  1239.              DIFFUSE 0.8
  1240.           END_TEXTURE
  1241.      END_OBJECT
  1242.  
  1243. The real power of declaration becomes apparent when you declare
  1244. several primitive types of objects and then define an object with
  1245. several component shapes, using either COMPOSITE methods or the CSG
  1246. methods INTERSECTION, UNION, or DIFFERENCE.  Also, using the
  1247. DECLARE keyword to pre- define textures can make several objects
  1248. share a texture without the need for each object to store a
  1249. duplicate copy of the same texture, for more efficient memory
  1250. usage. Example:
  1251.  
  1252.      DECLARE Dull TEXTURE  { A Basic, Boring Texture }
  1253.           AMBIENT 0.3
  1254.           DIFFUSE 0.7
  1255.      END_TEXTURE
  1256.  
  1257.      OBJECT         { A Hot dog in a Hamburger Bun (?) }
  1258.           UNION
  1259.                QUADRIC Sphere
  1260.                     SCALE <20.0, 10.0, 20.0>
  1261.             TEXTURE Dull END_TEXTURE
  1262.                END_QUADRIC
  1263.                QUADRIC Cylinder_X
  1264.                     SCALE <40.0, 20.0, 20.0>
  1265.             TEXTURE Dull END_TEXTURE
  1266.                END_QUADRIC
  1267.           END_UNION
  1268.      END_OBJECT
  1269.  
  1270.  
  1271. Layered textures, new to version 2.10, may also be DECLARE'd.  The
  1272. DECLARE mechanism keeps looking for successive TEXTURE definitions
  1273. and will layer them onto the same texture until another DECLARE (or
  1274. any other statement except another TEXTURE) is encountered in the
  1275. input data file.  For example:
  1276.  
  1277.  DECLARE Cloud_Wood TEXTURE  { This is the cloudy wood texture used
  1278. earlier. }    Dark_Wood
  1279.    TURBULENCE 0.0
  1280.    SCALE <0.2 0.2 0.2>
  1281.    PHONG 1.0
  1282.  END_TEXTURE
  1283.  TEXTURE { This is layered onto the wood texture just defined. }  
  1284.  TURBULENCE 0.5
  1285.    BOZO
  1286.    COLOUR_MAP
  1287.      { transparent to transparent }
  1288.      [0.0 0.6   COLOUR RED 1.0 GREEN 1.0 BLUE 1.0 ALPHA 1.0       
  1289.                 COLOUR RED 1.0 GREEN 1.0 BLUE 1.0 ALPHA 1.0]
  1290.  
  1291.      { transparent to white }
  1292.      [0.6 0.8   COLOUR RED 1.0 GREEN 1.0 BLUE 1.0 ALPHA 1.0       
  1293.                 COLOUR RED 1.0 GREEN 1.0 BLUE 1.0]
  1294.  
  1295.      { white to grey }
  1296.      [0.8 1.001 COLOUR RED 1.0 GREEN 1.0 BLUE 1.0
  1297.                 COLOUR RED 0.8 GREEN 0.8 BLUE 0.8]
  1298.    END_COLOUR_MAP
  1299.    SCALE <0.4  0.08  0.4>
  1300.  END_TEXTURE
  1301.  
  1302. DECLARE (etc.) { Ends the definition of the layered "Cloud_Wood"
  1303. texture. }
  1304.  
  1305. 6.2.2)  Viewpoint
  1306.  
  1307. The viewpoint tells the ray tracer the location and orientation of
  1308. the camera. The viewpoint is described by four vectors - Location,
  1309. Direction, Up, and Right.  Location determines where the camera is
  1310. located.  Direction determines the direction that the camera is
  1311. pointed.  Up determines the "up" direction of the camera.  Right
  1312. determines the direction to the right of the camera.
  1313.  
  1314. A first principle's declaration of a viewpoint would look like
  1315. this:      
  1316.      VIEWPOINT
  1317.           LOCATION < 0.0  0.0  0.0>
  1318.           DIRECTION < 0.0  0.0  1.0>
  1319.           UP < 0.0  1.0  0.0 >
  1320.           RIGHT < 1.0  0.0  0.0>
  1321.      END_VIEWPOINT
  1322.  
  1323. This format becomes cumbersome, however, because the vectors must
  1324. be hand calculated.  This is especially difficult when the vectors
  1325. are not lined up with the X, Y, and Z axes as they are in the above
  1326. example. To make it easier to define the viewpoint, you can define
  1327. one viewpoint, then modify the description.  For example,
  1328.  
  1329.      VIEWPOINT
  1330.           LOCATION < 0.0  0.0  0.0>
  1331.           DIRECTION < 0.0  0.0  1.0>
  1332.           UP < 0.0  1.0  0.0 >
  1333.           RIGHT < 1.0  0.0  0.0 >
  1334.           TRANSLATE < 5.0  3.0  4.0 >
  1335.           ROTATE < 30.0  60.0  30.0 >
  1336.      END_VIEWPOINT
  1337.  
  1338. In this example, the viewpoint is created, then translated to
  1339. another point in space and rotated by 30 degrees about the X axis,
  1340. 60 degrees about the Y axis, and 30 degrees about the Z axis.
  1341.  
  1342. Unfortunately, even this is somewhat cumbersome.  So, in version
  1343. 2.0 and above, you can now specify two more parameters:
  1344.  
  1345.           SKY <vector>
  1346.           LOOK_AT <vector>
  1347.  
  1348. The SKY keyword tells the viewpoint where the sky is.  It tries to
  1349. keep the camera's UP direction aligned as closely as possible to
  1350. the sky. The LOOK_AT keyword tells the camera to look at a specific
  1351. point.  The camera is rotated as required to point directly at that
  1352. point.  By changing the SKY vector, you can twist the camera while
  1353. still looking at the same point.
  1354.  
  1355. One subtle point:  the SKY direction is not necessarily the same as
  1356. the UP direction.  For example, consider the following situation:
  1357.  
  1358.           S^
  1359.            | /U
  1360.            |/
  1361.            C
  1362.             \
  1363.              \
  1364.               \
  1365.                O
  1366.  
  1367. If you said that the camera C has a SKY direction S and is looking
  1368. at O, the up direction will not point to the sky.  UP's like
  1369. putting an antenna on your camera.  If you point the camera
  1370. downwards, the antenna will no longer point straight up.
  1371.  
  1372. The RIGHT vector, as was mentioned previously, controls the aspect
  1373. ratio of the screen display.  It also determines the "handedness"
  1374. of the coordinate system in use.  A normal (left-handed) RIGHT
  1375. statement would be:
  1376.  
  1377.     RIGHT < 1.3333 0.0 0.0 >
  1378.  
  1379. To use a right-handed coordinate system, as is popular in some CAD
  1380. programs and some other ray-tracers, such as Sculpt for the Amiga,
  1381. use a RIGHT like:
  1382.  
  1383.     RIGHT < -1.3333 0.0 0.0 >
  1384.  
  1385. Some CAD systems also have the peculiar conception that the Z axis
  1386. is the "elevation" and is the "UP" direction instead of the Y axis. 
  1387. If this is the case you will want to change your "UP" statement to:
  1388.  
  1389.     UP < 0.0 0.0 1.0 >
  1390.  
  1391. Note that a pinhole camera model is used, so no focus or depth-of-
  1392. field effects are supported at this time.  For more detailed
  1393. information on the camera model, see the section "How it All
  1394. Works."
  1395.  
  1396. 6.2.3)  Fog
  1397.  
  1398. The raytracer includes the ability to render fog.  To add fog to a
  1399. scene, place the following declaration outside of any object
  1400. definitions:
  1401.  
  1402.      FOG
  1403.           COLOUR  {... the fog colour}
  1404.           200.0   {... the fog distance}
  1405.      END_FOG
  1406.  
  1407. The fog to colour ratio is calculated as 1-exp(-depth/distance), so
  1408. at depth 0, the colour is pure (1.0) with no fog (0.0).  At the fog
  1409. distance, you'll get 63% of the colour from the object's colour and
  1410. 37% from the fog colour.
  1411.  
  1412. 6.2.4)  Shapes
  1413.  
  1414. Shapes describe the shape of an object without mentioning any
  1415. surface characteristics like colour, surface lighting and
  1416. reflectivity.
  1417.  
  1418. 6.2.4.1)    Quadric Shapes
  1419.  
  1420. The most general shape used by this system is called a Quadric
  1421. Surface. Quadric Surfaces can produce shapes like spheres, cones,
  1422. cylinders, paraboloids (dish shapes), and hyperboloids (saddle or
  1423. hourglass shapes).
  1424.  
  1425. The easiest way to define these shapes is to include the standard
  1426. file "shapes.dat" into your program and to transform these shapes
  1427. (using TRANSLATE, ROTATE, and SCALE) into the ones you want.  To be
  1428. complete, however, I will describe the mathematical principles
  1429. behind quadric surfaces.  Those who are not interested in the
  1430. mathematical details can skip to the next section. 
  1431.  
  1432. The quadric:
  1433.  
  1434.       QUADRIC
  1435.           <A B C>
  1436.           <D E F>
  1437.           <G H I>
  1438.           J
  1439.       END_QUADRIC
  1440.  
  1441. defines a surface in three dimensions which satisfies the following
  1442. equation:
  1443.  
  1444.  
  1445.        A y**2  + B y**2  + C z**2
  1446.      + D xy    + E xz    + F yz
  1447.      + G x     + H y     + I z    + J = 0
  1448.  
  1449.  
  1450. (Did you really want to know that?  I didn't think so. :-)  DKB)
  1451.  
  1452. Different values of A,B,C,...J will give different shapes.  So, if
  1453. you take any three dimensional point and use its x, y, and z
  1454. coordinates in the above equation, the answer will be 0 if the
  1455. point is on the surface of the object. The answer will be negative
  1456. if the point is inside the object and positive if the point is
  1457. outside the object.  Here are some examples:
  1458.  
  1459.      X**2 + Y**2 + Z**2 - 1 = 0     Sphere
  1460.      X**2 + Y**2 - 1 = 0            Cylinder along the Z axis     
  1461.      X**2 + Y**2 - Z**2 = 0         Cone along the Z axis
  1462.  
  1463.  
  1464. 6.2.4.2)    Quadric surfaces the easy way
  1465.  
  1466. Now that doesn't sound so hard, does it?  Well, actually, it does. 
  1467. Only the hard-core graphics fanatic would define his objects using
  1468. the QUADRIC definition directly.  Even I don't do it that way and
  1469. I know how it works (Well, at least I worked it out once or twice
  1470. :-) - DKB).
  1471.  
  1472. Fortunately, there is an easier way. The file "shapes.dat" already
  1473. includes the definitions of many quadric surfaces.  They are
  1474. centered about the origin < 0 0 0 > and have a radius of 1.  To use
  1475. them, you can define shapes simply as follows:
  1476.  
  1477.       INCLUDE "colors.dat"
  1478.       INCLUDE "shapes.dat"{ This is the important one for this
  1479. example }       
  1480.       INCLUDE "textures.dat"
  1481.  
  1482.      QUADRIC
  1483.           Cylinder_X
  1484.           SCALE < 50.0  50.0  50.0 >
  1485.           ROTATE < 30.0  10.0  45.0 >
  1486.           TRANSLATE < 2.0  5.0  6.0 >
  1487.      END_QUADRIC
  1488.  
  1489.  
  1490. You may have as many transformation lines (scale, rotate, and
  1491. translate) as you like in any order.  Usually, however, it's
  1492. easiest to do a scale first, one or more rotations, then finally a
  1493. translation.  Otherwise, the results may not be what you expect.
  1494. (The transformations always transform the object about the origin. 
  1495. If you have a sphere at the origin and you translate it then rotate
  1496. it, the rotation will spin the sphere around the origin like
  1497. planets about the sun).
  1498.  
  1499.  
  1500.  
  1501. 6.2.4.3)    Spheres
  1502.  
  1503. Since spheres are so common in ray traced graphics, A SPHERE
  1504. primitive has been added to the system.  This primitive will render
  1505. much more quickly than the corresponding quadric shape.  The syntax
  1506. is:
  1507.  
  1508.      SPHERE  <center> radius END_SPHERE
  1509.  
  1510. You can also add translations, rotations, and scaling to the
  1511. sphere. For example, the following two objects are identical:
  1512.  
  1513.      OBJECT
  1514.           SPHERE  < 0.0 25.0 0.0 > 10.0 END_SPHERE
  1515.           TEXTURE
  1516.              COLOR Blue
  1517.              AMBIENT 0.3
  1518.              DIFFUSE 0.7
  1519.           END_TEXTURE
  1520.      END_OBJECT
  1521.  
  1522.      OBJECT
  1523.           SPHERE  < 0.0 0.0 0.0 > 1.0
  1524.                TRANSLATE <0.0  25.0  0.0> 
  1525.                SCALE <10.0  10.0  10.0>
  1526.           END_SPHERE
  1527.           TEXTURE
  1528.              COLOR Blue
  1529.              AMBIENT 0.3
  1530.              DIFFUSE 0.7
  1531.           END_TEXTURE
  1532.      END_OBJECT
  1533.  
  1534. Note that Spheres may only be scaled uniformly. You cannot use:
  1535.  
  1536.      SCALE <10.0 5.0 2.0>
  1537.  
  1538. on a sphere.  If you need oblate (flattened) spheroids, use a
  1539. scaled quadric "QSphere" shape instead, as it can be arbitrarily
  1540. scaled in any dimension.
  1541.  
  1542. 6.2.4.4)    Planes
  1543.  
  1544. Another primitive provided to speed up the raytracing is the PLANE.
  1545. This is a flat infinite plane.  To declare a PLANE, you specify the
  1546. direction of the surface normal to the plane (the UP direction) and
  1547. the distance from the origin of the plane to the world's origin. As
  1548. with spheres, you can translate, rotate, and scale planes. 
  1549. Examples:
  1550.  
  1551.      PLANE <0.0  1.0  0.0> -10.0 END_PLANE   { A plane in the X-Z
  1552. axes 10 units below the world origin. }
  1553.  
  1554.      PLANE <0.0  1.0  0.0>  10.0 END_PLANE   { A plane in the X-Z
  1555. axes 10 units above the world origin. }
  1556.  
  1557.      PLANE <0.0  0.0  1.0>  -10.0 END_PLANE  { A plane in the X-Y
  1558. axes 10 units behind the world origin.}
  1559.  
  1560.  
  1561.  
  1562. 6.2.4.5)    Triangles
  1563.  
  1564. In order to make more complex objects than the class of quadrics
  1565. will permit, a new primitive shape for triangles has been added. 
  1566. There are two different types of triangles:  flat shaded triangles
  1567. and smooth shaded (Phong) triangles.
  1568.  
  1569. Flat shaded triangles are defined by listing the three vertices of
  1570. the  triangle.  For example:
  1571.    
  1572.      TRIANGLE  < 0.0   20.0  0.0>
  1573.                < 20.0  0.0   0.0>
  1574.                <-20.0  0.0   0.0>
  1575.      END_TRIANGLE
  1576.  
  1577. The smooth shaded triangles use Phong Normal Interpolation to
  1578. calculate the surface normal for the triangle.  This makes the
  1579. triangle appear to be a smooth curved surface.  In order to define
  1580. a smooth triangle, however, you must supply not only the vertices,
  1581. but also the surface normals at those vertices.  For example:
  1582.    
  1583.      SMOOTH_TRIANGLE
  1584.           {      points             surface normals     }
  1585.           <  0.0  30.0  0.0 >    <0.0   0.7071   -0.7071>
  1586.           < 40.0 -20.0  0.0 >    <0.0   -0.8664  -0.5   >
  1587.           <-50.0 -30.0  0.0 >    <0.0   -0.5     -0.8664>
  1588.      END_SMOOTH_TRIANGLE
  1589.  
  1590. As with the other shapes, triangles can be translated, rotated, and
  1591. scaled.
  1592.  
  1593. NOTE 1:  Triangles cannot be used in CSG INTERSECTION or DIFFERENCE
  1594. types (described next) since triangles have no clear "inside".  The
  1595. CSG UNION type works acceptably, but with no real difference from
  1596. a COMPOSITE made up of TRIANGLE primitives.
  1597.  
  1598. NOTE 2:  To be honest, I don't expect mere mortals to work out the
  1599. surface normals of triangles.  Ideally, you'd have another program
  1600. generate them for you.  See the section on "Common Questions and
  1601. Answers" for details on how this might be done.
  1602.  
  1603.  
  1604. 6.2.4.6)    Quartic Surfaces
  1605.  
  1606. Quartic surfaces are 4th order surfaces, and can be used to
  1607. describe a large class of shapes including the torus, the
  1608. lemniscate, etc.  The general equation for a quartic equation in
  1609. three variables is (hold onto your hat):
  1610.  
  1611.    a00 x^4 + a01 x^3 y + a02 x^3 z+ a03 x^3 + a04 x^2 y^2 +     
  1612.    a05 x^2 y z + a06 x^2 y + a07 x^2 z^2 + a08 x^2 z + a09 x^2 +  
  1613.    a10 x y^3 + a11 x y^2 z + a12 x y^2 + a13 x y z^2 + a14 x y z + 
  1614.    a15 x y + a16 x z^3 + a17 x z^2 + a18 x z + a19 x +
  1615.    a20 y^4 + a21 y^3 z + a22 y^3+ a23 y^2 z^2 + a24 y^2 z + 
  1616.    a25 y^2 + a26 y z^3 + a27 y z^2 + a28 y z + a29 y + 
  1617.    a30 z^4 + a31 z^3 + a32 z^2 + a33 z + a34
  1618.  
  1619. To declare a quartic surface requires that each of the coefficients 
  1620. (a0 -> a34) be placed in order into a single long vector of 35
  1621. terms.
  1622.  
  1623. As an example, the following object declaration is for a torus
  1624. having major radius 6.3 minor radius 3.5 (Making the maximum width
  1625. just under 10).
  1626.  
  1627.      { Torus having major radius sqrt(40), minor radius sqrt(12) } 
  1628.     OBJECT
  1629.       QUARTIC
  1630.       < 1.0   0.0   0.0   0.0   2.0   0.0   0.0   2.0   0.0       
  1631.      -104.0   0.0   0.0   0.0   0.0   0.0   0.0   0.0   0.0       
  1632.         0.0   0.0   1.0   0.0   0.0   2.0   0.0  56.0   0.0       
  1633.         0.0   0.0   0.0   1.0   0.0 -104.0  0.0 784.0 >
  1634.       END_QUARTIC
  1635.       BOUNDED_BY
  1636.        SPHERE <0 0 0> 10 END_SPHERE
  1637.       END_BOUND
  1638.      END_OBJECT
  1639.  
  1640. The code to calculate Ray-Surface intersections for quartics is
  1641. somewhat slower than that for intersections with quadric surfaces. 
  1642. Benchmarks on a stock 8Mhz AT (with FPU) give results of around
  1643. 1400 solutions per second for 2nd order equations (quadrics) vs 444
  1644. per second for 3rd order equations and 123 per second for 4th order
  1645. equations (quartics).  So clever use of bounding shapes can make a
  1646. big difference in processing time.
  1647.  
  1648. While a great deal of time has gone into debugging the code for
  1649. handling quartic surfaces, I know for a fact that there are bad
  1650. combinations of surface equations and lighting orientations that
  1651. cause math errors (crash). If this happens to you, as the joke
  1652. goes, "then don't DO that."
  1653.  
  1654. Here are some quartic surfaces to get you started.
  1655.  
  1656. A Torus can be represented by the equation:
  1657.  
  1658.    x^4 + y^4 + z^4 + 2 x^2 y^2 + 2 x^2 z^2 + 2 y^2 z^2
  1659.    -2 (r0^2 + r1^2) x^2 + 2 (r0^2 - r1^2) y^2 - 2 (r0^2 - r1^2) z^2 
  1660.   + (r0^2 - r1^2)^2 = 0
  1661.  
  1662. Where r0 is the "major" radius of the torus - the distance from the
  1663. hole of the donut to the middle of the ring of the donut, and r1 is
  1664. the "minor" radius of the torus - the distance from the middle of
  1665. the ring of the donut to the outer surface.  Described another way,
  1666. a torus is a circle that is revolved around an axis.  The major
  1667. radius is the distance from the axis to the center of the circle,
  1668. the minor radius is the radius of the circle. (If this were a Mac
  1669. I could put a drawing in here to show you...)
  1670.  
  1671. Note that scaling surfaces like a torus scales everything. In order
  1672. to change the relationship between the size of the hole and the
  1673. size of the ring, it is necessary to enter new coefficients for the
  1674. torus.
  1675.  
  1676. The only coefficients of the 35 that need to be filled in are:
  1677.  
  1678.     a0  = a20 = a30 = 1,
  1679.     a4  = a7  = a23 = 2,
  1680.     a9  = a32       = -2 (r0^2 + r1^2)
  1681.     a25             = 2 (r0^2 - r1^2)
  1682.     a34             = 2 (r0^2 - r1^2)^2
  1683.  
  1684. the torus can then be rotated and translated into position once its
  1685. shape has been defined. (See 'TORUS.DAT')
  1686.  
  1687. A generalization of the lemniscate of Gerono can be represented by
  1688. the equation:
  1689.  
  1690.    c^2 x^4 - a^2 c^2 x^2 + y^2 + z^2 = 0
  1691.  
  1692. where good start values are a = 1.0 and c = 1.0, giving the
  1693. coefficients:
  1694.  
  1695.    a0 = a25 = a32 = 1,
  1696.    a9 = -1
  1697.  
  1698. (See the example file "LEMNISCA.DAT" for a more complete example)
  1699.  
  1700. A generalization of a piriform can be represented by the equation:
  1701.  
  1702.    -b c^2 x^4 - a c^2 x^3 + y^2 + z^2 = 0
  1703.  
  1704. where good start values are a = 4, b = -4, c = 1, giving the
  1705. coefficients
  1706.  
  1707.    a0 = 4,
  1708.    a3 = -4,
  1709.    a25 = a32 = 1
  1710.  
  1711. (See the file "PIRIFORM.DAT" for more on this...)
  1712.  
  1713. There are really so many different QUARTIC shapes, we can't even
  1714. begin to list or describe them all.  If you are interested and
  1715. mathematically inclied, an excellent reference book for curves and
  1716. surfaces where you'll find more QUARTIC shape formulas is:
  1717.  
  1718.    "The CRC Handbook of Mathematical Curves and Surfaces"
  1719.    David von Seggern
  1720.    CRC Press
  1721.    1990
  1722.  
  1723.  
  1724. 6.2.4.7)    Constructive Solid Geometry (CSG)
  1725.  
  1726. This ray tracer supports Constructive Solid Geometry in order to
  1727. make the object definition abilities more powerful.  Constructive
  1728. Solid Geometry allows you to define shapes which are the union,
  1729. intersection, or difference of other shapes.  Unions superimpose
  1730. the two shapes.  This has the same effect as defining two separate
  1731. objects, but is simpler to create and/or manipulate. Intersections
  1732. define the space where the two surfaces meet.  Differences allow
  1733. you to cut one object out of another.
  1734.  
  1735. CSG Intersections, Unions, and Differences can consist of two or
  1736. more shapes. They are defined as follows:
  1737.  
  1738.      OBJECT
  1739.           INTERSECTION
  1740.                QUADRIC
  1741.                     ...
  1742.                END_QUADRIC
  1743.  
  1744.                QUADRIC
  1745.                     ...
  1746.                END_QUADRIC
  1747.  
  1748.                QUADRIC
  1749.                     ...
  1750.                END_QUADRIC
  1751.           END_INTERSECTION
  1752.           ...
  1753.      END_OBJECT
  1754.  
  1755. UNION or DIFFERENCE may be used instead of INTERSECTION.  The order
  1756. of the shapes doesn't matter except for the DIFFERENCE shapes.  For
  1757. CSG differences, the first shape is visible and the remaining
  1758. shapes are cut out of the first (in reverse order from version 1.2
  1759. DIFFERENCE's).
  1760.  
  1761. Constructive solid geometry shapes may be translated, rotated, or
  1762. scaled in the same way as a Quadric surface.  The quadric surfaces
  1763. making up the CSG object may be individually translated, rotated,
  1764. and scaled as well.
  1765.  
  1766. When using CSG, it is often useful to invert an shape so that it's
  1767. inside-out. The INVERSE keyword can be used to do this for any
  1768. SPHERE, PLANE, or QUADRIC. When INVERSE is used, the "inside" of
  1769. the object is flipped to become the "outside".  For Planes,
  1770. "inside" is defined to be "in the opposite direction to the
  1771. "normal" or "up" direction.
  1772.  
  1773. Note that performing an INTERSECTION between an shape and some
  1774. other INVERSE shapes is the same as performing a DIFFERENCE.  In
  1775. fact, the DIFFERENCE is actually implemented in this way in the
  1776. code.
  1777.  
  1778. 6.2.5)  Objects
  1779.  
  1780. There is more to defining an object than just its shape.  You must
  1781. tell the ray tracer about the properties of the object like surface
  1782. colour, alpha, reflectivity, refractivity, the index of refraction,
  1783. and so on.  This may be done by specifying it in the shape or the
  1784. object.  Generally, an OBJECT definition will contain two pieces of
  1785. information about an object: First, what shape it is, and second,
  1786. what it's looks like (on the surface and throughout). A typical
  1787. object definition looks something like this:
  1788.  
  1789.      OBJECT
  1790.           QUADRIC QSphere
  1791.                TRANSLATE < 40.0 40.0 60.0 >
  1792.           END_QUADRIC
  1793.  
  1794.           TEXTURE
  1795.              AMBIENT  0.3
  1796.              DIFFUSE   0.7
  1797.              REFLECTION  0.3
  1798.              REFRACTION  0.3
  1799.              IOR 1.05
  1800.              COLOUR RED 1.0 GREEN 1.0 BLUE 1.0 ALPHA 0.5
  1801.           END_TEXTURE
  1802.      END_OBJECT
  1803.  
  1804. The following keywords may be used when defining objects:
  1805.  
  1806. 6.2.5.1)    COLOUR value
  1807.  
  1808. When used on an OBJECT (i.e., not inside a TEXTURE block), the
  1809. COLOUR keyword determines what colour to use for a low quality
  1810. rendering when TEXTURE's are ignored.  See the +q option for
  1811. details on setting the low-quality option.
  1812.  
  1813. Example:
  1814.  
  1815.      COLOUR RED 1.0  BLUE 0.4
  1816.  
  1817.           - or -
  1818.  
  1819.      DECLARE Yellow = COLOUR RED 1.0 GREEN 1.0
  1820.           ...
  1821.      COLOUR Yellow
  1822.  
  1823.  
  1824. 6.2.5.2)    TRANSLATE vector
  1825. 6.2.5.3)    ROTATE vector
  1826. 6.2.5.4)    SCALE vector
  1827.  
  1828. Objects can be translated, rotated, and scaled just like surfaces. 
  1829. If an object is transformed, all textures attached to the object at
  1830. that time are transformed as well.  This means that if you have a
  1831. TRANSLATE, ROTATE, or SCALE before a TEXTURE, the texture will NOT
  1832. be transformed.  If the SCALE TRANSLATE, or ROTATE is after the
  1833. TEXTURE, the texture will be transformed.
  1834.  
  1835. 6.2.5.5)    LIGHT_SOURCE
  1836.  
  1837. If the LIGHT_SOURCE keyword is used in the definition of an object,
  1838. then the object is included in the list of light sources.  It can
  1839. light objects and produce shadows.  (You should also specify the
  1840. COLOUR of the light source, it will usually be "White").  Light
  1841. sources have a peculiar restriction:  The light source MUST be
  1842. TRANSLATED to its final position in the scene, so the normal way to
  1843. define a light source is a sphere or quadric centered about the
  1844. origin, then TRANSLATED to where desired in the final scene.  For
  1845. example:
  1846.  
  1847.      OBJECT
  1848.           SPHERE <0.0  0.0  0.0> 2.0 END_SPHERE   {could be a
  1849. quadric, too.}           TRANSLATE <100.0  120.0  40.0>
  1850.  
  1851.           LIGHT_SOURCE
  1852.           COLOUR White      { This is the colour of the light
  1853. emitted }           TEXTURE
  1854.              COLOUR White   { This is the surface colour of the
  1855. sphere }              AMBIENT 1.0
  1856.              DIFFUSE 0.0
  1857.           END_TEXTURE
  1858.      END_OBJECT
  1859.  
  1860.  
  1861. NOTE: You MUST specify the colour of the light outside the TEXTURE
  1862. block. This       allows the renderer to quickly determine the
  1863. colour of the light source       without having to plow through the
  1864. textures.  Any colour information       inside the TEXTURE block is
  1865. used to render the light source object itself       if it is
  1866. visible in the scene.  The subtle difference between the      
  1867. actual sphere object and the light ray emanation point (the center
  1868. of       the sphere) is why LIGHT_SOURCE's must be defined at
  1869. (0,0,0) then       TRANSLATE'd to where you want them.  It ties
  1870. together and TRANSLATE's       both the object itself and the light
  1871. ray source point to the specified       point in the scene. 
  1872. Usually, light sources have an AMBIENT value of 1.0       and a
  1873. DIFFUSE of 0.0, but this is not a hard and fast rule.
  1874.  
  1875. 6.2.6)  TEXTURE
  1876.  
  1877. The texture feature is an experiment into functionally based
  1878. modelling.  This feature allows you to assign colouring schemes to
  1879. objects.  Many procedural surface textures are provided, and by
  1880. using different colour maps with them, nearly infinite permutations
  1881. are possible.  For example, you can make some object look like wood
  1882. or marble, etc.  In PV-Ray, any parameter that changes the
  1883. appearance of the surface MUST be put into a TEXTURE block.
  1884.  
  1885. The basic TEXTURE syntax is as follows:
  1886.  
  1887.      TEXTURE
  1888.           0.05
  1889.           WOOD
  1890.           TURBULENCE 0.2
  1891.           TRANSLATE < 1.0 2.0 3.0 >
  1892.           ROTATE < 0.0 10.0 40.0 >
  1893.           SCALE < 10.0 10.0 10.0 >
  1894.      END_TEXTURE
  1895.  
  1896. Transformations are optional.  They allow you to transform the
  1897. texture independent of the object itself.  If you are doing
  1898. animation, then the transformations should be the same as the
  1899. object transformations so that the texture follows the object
  1900. through 3-D space.
  1901.  
  1902. The floating-point value given immediately following the texture
  1903. keyword is an optional "texture randomness" value, which causes a
  1904. minor random scattering of calculated colour values and produces a
  1905. sort of "dithered" appearance.  Note this is BAD, BAD, BAD for
  1906. animations!!  This is the ONLY "truly random" thing in all of PV-
  1907. Ray, and will produce a most annoying flicker of flying pixels on
  1908. any textures animated with a "randomness" value used.
  1909.  
  1910. Instead of using WOOD, you may use MARBLE, BOZO, CHECKER, or a
  1911. handful of other interesting textures.  The WOOD and MARBLE
  1912. textures are perturbed by a turbulence function.  This makes them
  1913. look more random and irregular than they would normally appear. 
  1914. The amount of turbulence can be changed by the TURBULENCE keyword
  1915. followed by a number.  Values from 0.1 to 0.3 seem to give the best
  1916. results.  The default is 0.0, or no turbulence. 
  1917.  
  1918. Note some of the textures given are coloration textures, such as
  1919. MARBLE, WOOD CHECKER, GRANITE, and AGATE.  These work with colour
  1920. maps, and have default "colour maps" they resort to if none are
  1921. given.  The rest of the textures available are "surface
  1922. perturbation" textures, and do not directly affect the colour of
  1923. the object, but rather the surface's apparent orientation in space.
  1924. Examples of this are WAVES, RIPPLES, DENTS, BUMPS, and WRINKLES. 
  1925. Note that any given texture may include up to two actual textures,
  1926. one coloration and one surface perturbation choice per texture. 
  1927. This would allow rippled wood, or dented granite combinations,
  1928. etc., but, keep in mind that any texture transformations applied to
  1929. one texture (i.e. TRANSLATE or SCALE) will also transform the other
  1930. one in the same fashion.
  1931.  
  1932. As of version 2.10, it is possible to create layered textures. If
  1933. you use more that one texture block, the raytracer will compute the
  1934. colour of the last texture and if there's any transparency in the
  1935. colour (i.e., any alpha), it will mix in some of the colour from
  1936. the underlying textures.
  1937.  
  1938. IMPORTANT NOTE:  As of version 2.10, the keywords in this following
  1939. section  CANNOT be used outside of a TEXTURE-END_TEXTURE structure. 
  1940. this is a change in the input language from prior versions.
  1941.  
  1942. The following object surface lighting characteristics are
  1943. available:
  1944.  
  1945. 6.2.6.1)    AMBIENT value
  1946.  
  1947. Ambient light is light that is scattered everywhere in the room. 
  1948. An object lit only by ambient light will appear to have the same
  1949. brightness over the entire surface.  The default value is very
  1950. little ambient light (0.3).  The value can range from 0.0 to 1.0. 
  1951.  
  1952. 6.2.6.2)    DIFFUSE value
  1953.  
  1954. Diffuse light is light coming from a light source that is scattered
  1955. in all directions.  An object lit only by diffuse light looks like
  1956. a rubber ball with a spot light shining on it.  The value can range
  1957. from 0.0 to 1.0.  By default, there is mostly diffuse lighting
  1958. (0.7).
  1959.  
  1960. 6.2.6.3)    BRILLIANCE value
  1961.  
  1962. Objects can be made to appear more metallic by increasing their
  1963. brilliance. This controls the tightness of the basic diffuse
  1964. illumination on objects and minorly adjusts the appearance of
  1965. surface shininess.  The default value is 1.0.  Higher values from
  1966. 3.0 to about 10.0 can give objects a somewhat more shiny or
  1967. metallic appearance.  This is best used in concert with either the
  1968. SPECULAR or PHONG highlighting.
  1969.  
  1970. 6.2.6.4)    REFLECTION value
  1971.  
  1972. By setting the reflection value to be non-zero, you can give the
  1973. object a mirrored finish.  It will reflect all other objects in the
  1974. room.  The value can range from 0.0 to 1.0.  By default there is no
  1975. reflection. 
  1976.  
  1977. 6.2.6.5)    REFRACTION value
  1978.  
  1979. By setting the refraction value to be non-zero, the object is made
  1980. transparent. Light will be refracted through the object like a
  1981. lens.  The value can be set between 0.0 and 1.0.  There is no
  1982. refraction by default. 
  1983.  
  1984. NOTE 1:  New for 2.10:  In order to refraction to work properly,
  1985. you must have  some ALPHA component in the surface colour.  In the
  1986. places where the  ALPHA is high, the refracted light can get
  1987. through.  In places where  the ALPHA is low, the refracted light is
  1988. suppressed.  This is a  change in the input language from prior
  1989. versions.
  1990.  
  1991. NOTE 2:  The refracted light is filtered by (takes on) the surface
  1992. colour.
  1993.  
  1994. NOTE 3:  In layered textures, the REFRACTION and IOR keywords MUST
  1995. be in the last texture, otherwise they will not take effect.
  1996.  
  1997. NOTE 4:  If a texture has an ALPHA component and no value for
  1998. REFRACTION was supplied, the renderer will simply transmit the ray
  1999. through the surface with no bending.
  2000.  
  2001. 6.2.6.6)    IOR value
  2002.  
  2003. If the object is refracting light, then the IOR or Index of
  2004. Refraction should be set.  This determines how dense the object is. 
  2005. A value of 1.0 will give no refraction.  The Index of Refraction
  2006. for air is 1.0, water is 1.33, glass is 1.5, and diamond is 2.4. 
  2007.  
  2008. 6.2.6.7)    PHONG value
  2009.  
  2010. Controls the amount of Phong Specular Reflection highlighting on
  2011. the object. Causes bright shiny spots on the object, the colour of
  2012. the light source that is being reflected.  The size of the spot is
  2013. defined by the value given for PHONGSIZE below.  PHONG's value is
  2014. typically from 0.0 to 1.0, where 1.0 causes complete saturation of
  2015. the object's colour to the light source's colour at the brightest
  2016. area (center) of the highlight.  There is no PHONG highlighting
  2017. given by default. 
  2018.  
  2019. 6.2.6.8)    PHONGSIZE value
  2020.  
  2021. Controls the size of the PHONG Highlight on the object, sort of an
  2022. arbitrary "glossiness" factor.  Values range from 1.0 (Very Dull)
  2023. to 100 (Highly Polished).  Default PHONGSIZE is 40 (plastic?) if
  2024. not specified.  This is simulating the fact that slightly
  2025. reflective objects, especially metallic ones, have microscopic
  2026. facets, some of which are facing in the mirror direction.  The more
  2027. that are facing that way, the shinier the object appears, and the
  2028. tighter the specular highlights become.  Phong measures the average
  2029. of facets facing in the mirror direction from the light sources to
  2030. the viewer. 
  2031.  
  2032. 6.2.6.9)    SPECULAR value
  2033.  
  2034. Very similar to PHONG Specular Highlighting, but a better model is
  2035. used for determining light ray/object intersection, so a more
  2036. credible spreading of the highlights occur near the object
  2037. horizons, supposedly.  PHONG is thus included for mostly academic
  2038. reasons, but try them both and you decide which you like better. 
  2039. This effect is most obvious for light sources behind objects.  The
  2040. size of the spot is defined by the value given for ROUGHNESS below. 
  2041. Like PHONG, SPECULAR values are typically from 0.0 to 1.0 for full
  2042. saturation. Default is no SPECULAR highlighting.
  2043.  
  2044. Note that Specular and Phong highlights are NOT mutually exclusive. 
  2045. It is possible to specify both and they will both take effect. 
  2046. Normally, however, you will only specify one or the other.
  2047.  
  2048. 6.2.6.10)   ROUGHNESS value
  2049.  
  2050. Controls the size of the SPECULAR Highlight on the object, relative
  2051. to the object's "roughness".  Values range from 1.0 (Very Rough) to
  2052. 0.001 (Very Smooth).  The default value, if not specified, is 0.05
  2053. (Plastic?).  The roughness or average directional distribution of
  2054. the microfacets facing in the same direction as the perpendicular
  2055. surface "normal" cause the most notable reflection of the highlight
  2056. to the observer.
  2057.  
  2058.  
  2059. 6.2.6.11)   METALLIC
  2060.  
  2061. This keyword indicates that the colour of the specular and phong
  2062. hightlights will be the surface colour instead of the lightsource
  2063. colour.  This creates a metallic appearance.  When using this
  2064. feature, you should set AMBIENT to about 0.5 and set DIFFUSE to
  2065. 0.0.
  2066.  
  2067.  
  2068. The following advanced procedural textures are available:
  2069.  
  2070. 6.2.6.12)   CHECKER - A colouring texture.
  2071.  
  2072. CHECKER texturing gives a checker-board appearance.  This option
  2073. works best on planes.  When using the CHECKER texturing, you must
  2074. specify two colours immediately following the word CHECKER.  These
  2075. colours are the colours of alternate squares in the checker
  2076. pattern.  The default orientation of the CHECKER texture is on an
  2077. X-Z plane (good for ground work, etc.) but to use it on an object
  2078. which has mostly X-Y orientation (such as a sphere, for instance),
  2079. you must ROTATE the texture. 
  2080.  
  2081. To rotate the CHECKER texture onto an X-Y plane:
  2082.  
  2083.      TEXTURE
  2084.           CHECKER COLOUR White COLOUR Red
  2085.           SCALE <10.0 10.0 10.0>
  2086.           ROTATE <-90.0 0.0 0.0>   { Checkers now in the X-Y
  2087. plane... }      END_TEXTURE
  2088.  
  2089. 6.2.6.13)   CHECKER_TEXTURE - A colouring texture.
  2090. I've had many requests for a checker pattern to allow you to
  2091. alternate between wood and marble or any other two textures.  So,
  2092. in version 2.10, I've added a texture called CHECKER_TEXTURE that
  2093. takes two textures instead of two colours.
  2094.  
  2095. In order to support layered textures, I've made the syntax a bit
  2096. more verbose than it would be otherwise.  The syntax is:
  2097.  
  2098.     TEXTURE
  2099.        CHECKER_TEXTURE
  2100.           TEXTURE ... put in a texture here ... END_TEXTURE       
  2101.    TEXTURE ... add optional layers on top of that one ...
  2102. END_TEXTURE        TILE2
  2103.           TEXTURE ... this is the second tile texture END_TEXTURE 
  2104.          TEXTURE ... a texture layered on top of the second tile
  2105. END_TEXTURE        END_CHECKER_TEXTURE
  2106.        AMBIENT ...
  2107.        DIFFUSE ...
  2108.    END_TEXTURE
  2109.  
  2110. Note that the textures in CHECKER_TEXTURE only use the surface
  2111. colouring texture information.  Information about AMBIENT, DIFFUSE,
  2112. REFLECTION, etc. and surface normal information (WAVES, RIPPLES)
  2113. are ignored inside the CHECKER_TEXTURE. (hey, what do you want for
  2114. a 10 minute change?)
  2115.  
  2116.  
  2117. 6.2.6.14)   BOZO - A colouring texture.
  2118.  
  2119. BOZO texture basically takes a noise function and maps it onto the
  2120. surface of an object.  This "noise" is well-defined for every point
  2121. in space.  If two points are close together, they will have noise
  2122. values that are close together.  If they are far apart, their noise
  2123. values will be fairly random relative to each other. 
  2124.  
  2125. As mentioned above, for coloration textures such as WOOD, MARBLE,
  2126. and BOZO, etc., you may change the colouring scheme by using a
  2127. colour map.  This map allows you to convert numbers from 0.0 to 1.0
  2128. (which are generated by the ray tracer) into ranges of colours. For
  2129. example, the default BOZO colouring can be specified by:
  2130.  
  2131.      TEXTURE
  2132.           BOZO
  2133.           COLOUR_MAP
  2134.                [0.0 0.4 COLOUR White COLOUR White]
  2135.                [0.4 0.6 COLOUR Green COLOUR Green]
  2136.                [0.6 0.8 COLOUR Blue COLOUR Blue]
  2137.                [0.8 1.0 COLOUR Red COLOUR Red]
  2138.           END_COLOUR_MAP
  2139.      END_TEXTURE
  2140.  
  2141. The easiest way to see how it works is to try it.  With a good
  2142. choice of colours it produces some of the most realistic looking
  2143. cloudscapes you have ever seen indoors!  Try a cloud color map such
  2144. as:
  2145.  
  2146.      TEXTURE
  2147.           BOZO
  2148.           TURBULENCE 1.0      { A blustery day.  For a calmer one,
  2149. try 0.2 }           COLOUR_MAP
  2150.                [0.0 0.5  COLOUR RED 0.5 GREEN 0.5 BLUE 1.0  {blue
  2151. to blue}                     COLOUR RED 0.5 GREEN 0.5 BLUE 1.0]
  2152.                [0.5 0.6  COLOUR RED 0.5 GREEN 0.5 BLUE 1.0  {blue
  2153. to white}                     COLOUR RED 1.0 GREEN 1.0 BLUE 1.0]
  2154.                [0.6 1.001 COLOUR RED 1.0 GREEN 1.0 BLUE 1.0 {white
  2155. to grey}                     COLOUR RED 0.5 GREEN 0.5 BLUE 0.5]
  2156.           END_COLOUR_MAP
  2157.           SCALE <800.0 800.0 800.0>
  2158.           TRANSLATE <200.0 400.0 100.0>
  2159.      END_TEXTURE
  2160.  
  2161. The color map above indicates that for small values of texture, use
  2162. a sky blue color solidly until about halfway turbulent, then fade
  2163. through to white on a fairly narrow range.  As the white clouds get
  2164. more turbulent and solid towards the center, pull the color map
  2165. toward grey to give them the appearance of holding water vapor
  2166. (like typical clouds). 
  2167.  
  2168. Check out sunset.dat for a really neat (but slow) sky pattern using
  2169. ALPHA.
  2170.  
  2171.  
  2172. 6.2.6.15)   SPOTTED - A colouring texture.
  2173.  
  2174. Spotted texture is a sort of swirled random spotting of the colour
  2175. of the object.  If you've ever seen a metal organ pipe up close you
  2176. know about what it looks like (a galvanized garbage can is
  2177. close...) Play with this one, it might render a decent cloudscape
  2178. during a very stormy day (?).  No extra keywords are required. 
  2179. Should work with colour maps.  With small scaling values, looks
  2180. like masonry or concrete.
  2181.  
  2182. 6.2.6.16)   AGATE - A colouring texture.
  2183.  
  2184. This texture is similar to Marble, but uses a different turbulence
  2185. function. The TURBULENCE keyword has no effect, and as such it is
  2186. always very turbulent.
  2187.  
  2188. 6.2.6.17)   GRADIENT - A colouring texture.
  2189.  
  2190. This is a specialized texture that uses approximate local
  2191. coordinates of an object to control colour map gradients.  This
  2192. texture ONLY works with colour maps (one MUST be given!) and has a
  2193. special <X, Y, Z> triple given after the GRADIENT keyword, which
  2194. specifies any (or all) axes to perform the gradient action on. 
  2195. Example: a Y gradient <0.0 1.0 0.0> will give an "altitude colour
  2196. map", along the Y axis.  Values given other than 0.0 are taken as
  2197. 1.0.
  2198. For smooth repeating gradients, you should use a "circular" colour
  2199. map, that is, one in which the first colour value (0.0) is the same
  2200. as the last one (1.001) so that it "wraps around" and will cause
  2201. smooth repeating gradient patterns.  Scaling the texture is
  2202. normally required to achieve the number of repeating shade cycles
  2203. you want.  Transformation of the texture is useful to prevent a
  2204. "mirroring" effect from either side of the central 0 axes.  Here is
  2205. an example of a gradient texture which uses a sharp "circular"
  2206. color mapped gradient rather than a smooth one, and uses both X and
  2207. Y gradients to get a diagonally-oriented gradient.  It produces a
  2208. dandy candy cane texture! 
  2209.  
  2210.      TEXTURE
  2211.           GRADIENT < 1.0 1.0 0.0 >
  2212.           COLOUR_MAP
  2213.                [0.00 0.25  COLOUR RED 1.0 GREEN 0.0 BLUE 0.0      
  2214.               COLOUR RED 1.0 GREEN 0.0 BLUE 0.0]
  2215.                [0.25 0.75  COLOUR RED 1.0 GREEN 1.0 BLUE 1.0      
  2216.               COLOUR RED 1.0 GREEN 1.0 BLUE 1.0]
  2217.                [0.75 1.001 COLOUR RED 1.0 GREEN 0.0 BLUE 0.0      
  2218.               COLOUR RED 1.0 GREEN 0.0 BLUE 0.0]
  2219.           END_COLOUR_MAP
  2220.           SCALE <30.0 30.0 30.0>
  2221.           TRANSLATE <30.0 -30.0 0.0>
  2222.      END_TEXTURE
  2223.  
  2224. You may also specify a TURBULENCE value with the gradient to give
  2225. a more irregular colour gradient.  This may help to do neat things
  2226. like fire or corona effects.
  2227.  
  2228.  
  2229. 6.2.6.18)   GRANITE - A colouring texture.
  2230.  
  2231. This texture uses a simple 1/f fractal noise function to give a
  2232. pretty darn good grey granite texture.  Typically used with small
  2233. scaling values (2.0 to 5.0).  Also looks good with a little
  2234. dithering (texture randomness).  Should work with colour maps, so
  2235. try your hand at pink granite or alabaster! 
  2236.  
  2237. 6.2.6.19)   RIPPLES - A surface perturbation texture.
  2238.  
  2239. As mentioned earlier, you may specify a surface perturbation
  2240. texture which can be used in conjunction with the above coloration
  2241. textures.  RIPPLES makes a surface look like ripples of water.  The
  2242. RIPPLES option requires a value to determine how deep the ripples
  2243. are:
  2244.  
  2245.      TEXTURE
  2246.           WOOD
  2247.           RIPPLES 0.3
  2248.           TRANSLATE < 1.0 2.0 3.0 >
  2249.           ROTATE < 0.0 10.0 40.0 >
  2250.           SCALE < 10.0 10.0 10.0 >
  2251.      END_TEXTURE
  2252. (In this case, the WOOD, MARBLE, or BOZO, etc. keywords are
  2253. optional).  If a different colouring is specified (WOOD, MARBLE, or
  2254. BOZO), then the COLOUR parameter is ignored (except for light
  2255. sources where it gives the light colour or when rendering with a
  2256. low -q option).
  2257.  
  2258.  
  2259. 6.2.6.20)   WAVES - A surface perturbation texture.
  2260.  
  2261. Another option that you may want to experiment with is called
  2262. WAVES.  This works in a similar way to RIPPLES except that it makes
  2263. waves with different frequencies.  The effect is to make waves that
  2264. look more like deep ocean waves. (I haven't done much testing on
  2265. WAVES, so I can't guarantee that it works very well). 
  2266.  
  2267. Both WAVES and RIPPLES respond to a texturing option called PHASE. 
  2268. The PHASE option allows you to create animations in which the water
  2269. seems to move.  This is done by making the PHASE increment slowly
  2270. between frames.  The range from 0.0 to 1.0 gives one complete cycle
  2271. of a wave.
  2272.  
  2273. The WAVES and RIPPLES textures also respond to a keyword called
  2274. FREQUENCY.  If you increase the frequency of the waves, they get
  2275. closer together.  If you decrease it, they get farther apart.
  2276.  
  2277.  
  2278. 6.2.6.21)   BUMPS - A surface perturbation texture.
  2279.  
  2280. Approximately the same turbulence function as SPOTTED, but uses the
  2281. derived value to perturb the surface normal.  This gives the
  2282. impression of a "bumpy" surface, random and irregular, sort of like
  2283. an orange.  After the BUMPS keyword, supply a single floating point
  2284. value for the amount of surface perturbation.  Values typically
  2285. range from 0.0 (No Bumps) to 1.0 (Extremely Bumpy).  Values beyond
  2286. 1.0 may do weird things.
  2287.  
  2288. 6.2.6.22)   DENTS - A surface perturbation texture.
  2289.  
  2290. Also a surface normal perturbing texture.  Interesting when used
  2291. with metallic textures, it gives impressions into the metal surface
  2292. that look like dents.  A single value is supplied after the DENTS
  2293. keyword to indicate the amount of denting required.  Values range
  2294. from 0.0 (Showroom New) to 1.0 (Insurance Wreck).  Use larger
  2295. values at your own risk, they will raise your rates, anyway... ;-)
  2296. Scale the texture to make the pitting more or less frequent.
  2297.  
  2298. 6.2.6.23)   WRINKLES - A surface perturbation texture.
  2299.  
  2300. This is sort of a 3-D (normal perturbing) GRANITE.  It uses a
  2301. similar 1/f fractal noise function to perturb the surface normal in
  2302. 3-D space.  With ALPHA values of greater than 0.0, could look like
  2303. wrinkled cellophane.  Requires a single value after the WRINKLES
  2304. keyword to indicate the amount of wrinkling desired.  Values from
  2305. 0.0 (No Wrinkles) to 1.0 (Very Wrinkled) are typical.
  2306. 6.2.6.24)   IMAGEMAP - A colouring texture.
  2307.  
  2308. This is a very special coloration texture that allows you to import
  2309. a bitmapped file in DUMP format (the format output by the ray-
  2310. tracer), IFF format or Compuserve GIF format and map that bitmap
  2311. onto an object.  In the texture of an object, you must give the
  2312. IMAGEMAP keyword, the format, and a file name.  The syntax is:
  2313.  
  2314.           IMAGEMAP [gradient] DUMP "filename" [ONCE]
  2315.      or   IMAGEMAP [gradient] IFF "filename" [ONCE]
  2316.      or   IMAGEMAP [gradient] GIF "filename" [ONCE]
  2317.  
  2318. The texture will then be mapped onto the object as a repeating
  2319. pattern.  The ONCE keyword places only one image onto the object
  2320. instead of an infinitely repeating tiled pattern.  When ONCE is
  2321. used, the colour outside the mapped texture is set to transparent. 
  2322. You can use the layered textures to place other textures or colours
  2323. below the image.
  2324.  
  2325. In version 2.10 and up, you can specify the ALPHA values for the
  2326. colour registers of IFF or GIF pictures (at least for the modes
  2327. that use colourmaps). You can do this by putting the keyword ALPHA
  2328. immediately following the filename followed by the register value
  2329. and transparency.  If the ALL keyword is used instead of a register
  2330. number, then all colours in that colourmap get that alpha value.
  2331.  
  2332. Eg.
  2333.           IMAGEMAP <1.0 -1.0 0.0> IFF "mypic.iff"
  2334.              ALPHA ALL 0.0
  2335.  
  2336.    ...or     ALPHA 0   0.5
  2337.              ALPHA 1   1.0
  2338.              ALPHA 2   0.3
  2339.              ...
  2340.  
  2341.           ONCE
  2342.           ...
  2343.  
  2344.  
  2345. By default, the image is mapped onto the X-Y plane in the range
  2346. (0.0, 0.0) to (1.0, 1.0).  If you would like to change this
  2347. default, you may use an optional gradient <x, y, z> vector after
  2348. the word IMAGEMAP.  This vector indicates which axes are to be used
  2349. as the u and v (local surface X-Y) axes.  The vector should contain
  2350. one positive number and one negative number to indicate the "u" and
  2351. "v" axes, respectively.  You may translate, rotate, and scale the
  2352. texture to map it onto the object's surface as desired.  Here is an
  2353. example:
  2354.  
  2355.      INCLUDE "shapes.data"
  2356.  
  2357.      OBJECT
  2358.           QUADRIC Plane_XY END_QUADRIC
  2359.           TRANSLATE <0.0  -20.0  0.0>
  2360.           TEXTURE
  2361.                { make this texture use the x and z axes for the
  2362. mapping. }                IMAGEMAP <1.0  0.0  -1.0> GIF "image.gif"
  2363.                SCALE <40.0 40.0 40.0>
  2364.           END_TEXTURE
  2365.      END_OBJECT
  2366.  
  2367. Filenames specified in the IMAGEMAP statements will be searched for
  2368. in the home (current) directory first, and if not found, will then
  2369. be searched for in directories specified by any "-l" (library path)
  2370. options active.  This would facilitate keeping all your imagemaps
  2371. (.dis, .gif or .iff) files in a "textures" subdirectory, and giving
  2372. an "-l" option on the command line to where your library of
  2373. imagemaps are. 
  2374.  
  2375. When I was bored with nothing to do, I decided that it would be
  2376. neat to have turbulent texture maps.  So, I said - "what the hell!" 
  2377. You can specify TURBULENCE with texture maps and it will perturb
  2378. the image.  It may give some bizarre results.  Is this useful?  I
  2379. dunno.  It was easy to do so I did it. Try it out and see what you
  2380. get.
  2381.  
  2382.  
  2383. 6.2.7)  Composite Objects
  2384.  
  2385. Often it's useful to combine several objects together to act as a
  2386. whole.  A car, for example, consists of wheels, doors, a roof, etc. 
  2387. A composite object allows you to combine all of these pieces into
  2388. one object.  This has two advantages.  It makes it easier to move
  2389. the object as a whole and it allows you to speed up the ray tracing
  2390. by defining bounding shapes that contain the objects.  (Rays are
  2391. first tested to see if they intersect the bounding shape. If not,
  2392. the entire composite object is ignored).  Composite objects are
  2393. defined as follows:
  2394.  
  2395.      COMPOSITE
  2396.           OBJECT
  2397.                ...
  2398.           END_OBJECT
  2399.  
  2400.           OBJECT
  2401.                ...
  2402.           END_OBJECT
  2403.           ...
  2404.  
  2405.           SCALE < 2.0 2.0 2.0 >
  2406.           ROTATE < 30.0 45.0 160.0 >
  2407.           TRANSLATE < 100.0 20.0 40.0 >
  2408.      END_COMPOSITE
  2409.  
  2410. Composite objects can contain other composite objects as well as
  2411. regular objects.  Composite objects cannot be light sources
  2412. (although any number of their components can).  This is because it
  2413. is nearly impossible to determine the true "center" of the
  2414. composite object, and our light sources are pinpoint ray sources
  2415. from the center of the light source object, wherever that may be.
  2416.  
  2417.  
  2418. 6.3)    Bounding Shapes
  2419.  
  2420. Let's face it.  This program is no speed demon.  You can save
  2421. yourself a lot of time, however, if you use bounding shapes around
  2422. any complex objects. Bounding shapes tell the ray tracer that the
  2423. object is totally enclosed by a simple shape.  When tracing rays,
  2424. the ray is first tested against the simple bounding shape.  If it
  2425. strikes the bounding shape, then the ray is further tested against
  2426. the more complicated object inside.
  2427.  
  2428. NOTE:  Don't use bounding shapes instead of CSG to clip objects. 
  2429. You will not get the result you want.  For the raytracer to work
  2430. properly, you must have the entire object inside the bounding
  2431. shape.
  2432.  
  2433. To use bounding shapes, you simply include the following lines into
  2434. the declaration of your OBJECT or COMPOSITE_OBJECT:
  2435.  
  2436.      BOUNDED_BY
  2437.           a shape
  2438.      END_BOUND
  2439.  
  2440. An example of a Bounding Shape:
  2441.  
  2442.      OBJECT
  2443.           INTERSECTION
  2444.                SPHERE <0.0 0.0 0.0> 2.0 END_SPHERE
  2445.                PLANE <0.0 1.0 0.0> 0.0 END_PLANE
  2446.                PLANE <1.0 0.0 0.0> 0.0 END_PLANE
  2447.           END_INTERSECTION
  2448.  
  2449.           BOUNDED_BY
  2450.                SPHERE <0.0 0.0 0.0> 2.0 END_SPHERE
  2451.           END_BOUND
  2452.      END_OBJECT
  2453.  
  2454. The best bounding shape is a SPHERE since this shape is highly
  2455. optimized.  Any shape may be used, however, if more convenient.
  2456.  
  2457.  
  2458.  
  2459. 7)  Displaying the Images
  2460.  
  2461. When the ray tracer draws the picture on the screen, it doesn't
  2462. make good choices for the colour registers.  Without knowing all
  2463. the needed colours ahead of time, only approximate guesses can be
  2464. made.  Usually, a post-processor is really needed to view the final
  2465. image correctly.
  2466.  
  2467. 7.1)    Amiga Systems
  2468.  
  2469. A post-processor has been provided for the Amiga which scans the
  2470. picture and chooses the best possible colour registers.  It then
  2471. redisplays the picture. For the Amiga, "DumpToIFF" can optionally
  2472. save this picture in IFF format. The syntax for the DumpToIFF post-
  2473. processor is:
  2474.  
  2475.      DumpToIFF filename
  2476.  
  2477. where the filename is the one given in the -o parameter of the ray
  2478. tracer.  If you didn't specify the -o option, then use:
  2479.  
  2480.      DumpToIFF data.dis
  2481.  
  2482. If you want to save to an IFF file, then put the name of the IFF
  2483. file after the name of the data file:
  2484.  
  2485.      DumpToIFF data.dis picture
  2486.  
  2487. This will create a file called "picture" which contains the IFF
  2488. image.
  2489.  
  2490.  
  2491. An alternative approach is to buy the commercial package called
  2492. "The Art Department" from ASDG.  You can then use the +fr option of
  2493. the raytracer to produce raw files which can be read in to TAD
  2494. using Sculpt mode.  You can also render using +fd to produce a dump
  2495. format file, and use d2iff to convert this to a 24-bit IFF image to
  2496. load into TAD.
  2497.  
  2498.  
  2499. 7.2)    IBM Systems
  2500.  
  2501. For the IBM, you will probably want to use the +ft option (default
  2502. if +f is given) and write the image out in Targa-24 format.  If you
  2503. have a Targa or compatible display adapter, you may view the
  2504. picture in the full 16 million colors (that's why they still cost
  2505. the big $$ bucks, but Hercules and Everex, notably, are introducing
  2506. their lower-priced SVGA-compatible 24-bit color display systems for
  2507. the IBM PC and compatibles).  If you don't have one of these, there
  2508. are several different post-processing programs available to convert
  2509. the TARGA true-color image into a more suitable color-mapped image
  2510. (such as .GIF).  If you have a VGA/MCGA or SVGA adapter capable of
  2511. 320x200 by 256 colors or better, then you may use the +d option
  2512. which will display the image as it generates using only approximate
  2513. screen colors.  The +d option will Autodetect the type of display
  2514. adapter card you have and briefly say what kind it found before
  2515. displaying the picture.  If you say +dx where x is one of the
  2516. predefined IBM (S)VGA display adapter types, no hardware test is
  2517. performed, so if you don't have that type of (S)VGA card, -> DON'T
  2518. <- use that particular +dx option!
  2519.  
  2520. When displaying the image to screen, a HSV conversion method is
  2521. used (hue, saturation, value).  This is a convenient way of
  2522. translating colors from a "true color" format (16 million) down a
  2523. "colour mapped" format of something reasonable (like 256), while
  2524. still approximating the color as closely as the available display
  2525. hardware permits.  As mentioned previously, the tracer has no way
  2526. of knowing which colors will be finally used in the image, nor can
  2527. it deal properly with all of the colors which will be generated (up
  2528. to 16M), so only 4 shades each of 64 possible hues are mapped into
  2529. the palette DAC, as well as black, white, and two grey levels. The
  2530. advantage a post-processor has in choosing mapped colors is that it
  2531. can throw away all the unused colors in the palette map, and
  2532. thereby free up some space for making better gradient shades of the
  2533. colors that are actually used.
  2534.  
  2535. There are several available image processing programs that can do
  2536. this, a public domain one that is very good is PICLAB, by the Stone
  2537. Soup Group (the folks who brought you FRACTINT).  The procedure is
  2538. to load the TARGA file, then use the MAKEPAL command to generate a
  2539. 256 color map which is the histogram-weighted average of the most-
  2540. used colors in the image (You could also PLOAD a palette file from
  2541. FRACTINT or one you previously had saved using PSAVE).  You then
  2542. MAP the palette onto the image one of two ways:
  2543.  
  2544.      1)   If the DITHER variable is OFF, a nearest-match-color-fit
  2545. is used,  which can sometimes produce unwanted "banding" of colored
  2546. regions  (called false contours).
  2547.      2)   If the DITHER variable is ON, then a standard dither is
  2548. used to  determine final color values.  This is much better at
  2549. blending the  color bands, but can produce noise in reflections and
  2550. make mirrors  appear dirty or imperfect.
  2551.  
  2552. Then you would typically SHOW the image or GSAVE it into GIF
  2553. format.  While the picture is still in the unmapped form (TARGA,
  2554. etc.) you can perform a variety of advanced image processing
  2555. transformations and conversions, so save the .TGA or .RAW files you
  2556. make (in case you ever get a TARGA card, or give them to a friend
  2557. who has one!).
  2558.  
  2559. A commercial product that also does a good job of nearest-match-
  2560. color-fit is the CONVERT utility of The AutoDesk Animator. 
  2561. However, the dither effect is not as good as that of PICLAB.  To
  2562. convert the file in AA's CONVERT, you LOAD TARGA, then in the
  2563. CONVERT menu, go to the SCALE function and just hit RENDER. Click
  2564. on the DITHER (lights up with an asterisk when on) if you want it
  2565. to use it's dithering.  CONVERT will scale (if asked to) and then
  2566. do a histogram of total used colors like PICLAB, but then makes 7
  2567. passes on the color map and image to determine shading thresholds
  2568. of each hue.  This nearly eliminates the color banding (false
  2569. contours) in a lot of cases without resorting to good 'ol
  2570. dithering.  By now you must get the feeling DITHER is a 4-letter
  2571. word.  If you have a low-resolution display, it is.  If you have
  2572. too few colors, however, it can be a saving grace.  At resolutions
  2573. of 640x400 or higher the "spray paint" effect of dithering and
  2574. anti-aliasing is much less noticeable, and effects a much smoother
  2575. blending appearance.
  2576.  
  2577. A new package to show up in the public domain/shareware circles for
  2578. the IBM is something called Image Alchemy, by Handmade Software. 
  2579. It will convert TARGA format to GIF files and do a decent job of
  2580. palette selection and dithering.  To use it simply say "ALCHEMY
  2581. file.tga file.gif -g -8 -c256". It also features a quick-and-dirty
  2582. display mode where it uses a standardized palette in much the same
  2583. way PV-Ray's +d option does, but offers dithering of the image
  2584. while using the pre-defined palette, for a somewhat better quick
  2585. display.
  2586.  
  2587.  
  2588. 7.3)    Unix Systems
  2589.  
  2590. I don't have many details on Unix systems, but I hear that the FBM
  2591. utilities work well to convert the Dump format files into various
  2592. formats of images. For people with access to anonymous FTP over
  2593. USENET, the FBM utilities are available from nl.cs.emu.edu
  2594. (128.2.222.56) in directory /usr/mlm/ftp.
  2595.  
  2596.  
  2597.  
  2598. 8)  PV-Ray Utilities
  2599.  
  2600. In many cases, creating data files for PV-Ray is difficult and
  2601. tedious.  To help remedy this problem, I and various other people
  2602. have developed some utilities to create data files.  These
  2603. utilities are described below.
  2604.  
  2605. As well, there are some utilities that perform operations on the
  2606. image files created by PV-Ray.  These utilities convert between
  2607. various formats and allow you to modify or merge output files
  2608. together.
  2609.  
  2610. I'd like to thank all the people who wrote these utilities and sent
  2611. them to me.  If anybody else comes up with other utilities, please
  2612. let me know and I'll include them in the distribution.
  2613.  
  2614. Some of these utilities are written in BASIC in IBM systems.  As
  2615. such, they are not easily portable from system to system.  If
  2616. anyone wants to convert them to C, let me know and I'll post the C
  2617. versions.
  2618.  
  2619. 8.1)    Data File Creation Utilities
  2620.  
  2621. The data creation utilities fall into two categories:  Those that
  2622. convert from some other format into PV-Ray format, and those that
  2623. generate PV-Ray files using algorithmic techniques.  These
  2624. utilities are described below.
  2625.  
  2626. 8.1.1)  SA2DKB
  2627.  
  2628. This program converts Sculpt-Animate 3D & 4D data files into
  2629. DKB/PV-Ray format.  It currently only supports the basic triangles
  2630. and textures. It doesn't support smooth triangles (it treats them
  2631. like normal triangles), light sources, cameras, or floors. 
  2632.  
  2633. (This utility was formerly called "Sculpt2DKB" but the IBM systems
  2634. out there kept calling it "SCULPT2D", then couldn't figure out what
  2635. a 2D program had to do with raytracing or what the nonexistent
  2636. Amiga program called "Sculpt-2D" was :-)
  2637.  
  2638. 8.1.2)  DXF2DKB
  2639.  
  2640. This utility converts AutoCAD DXF (Drawing eXchange Format) files
  2641. into DKB/PV-Ray format scene description files.  It was written by
  2642. Aaron Collins.  It does not support all of the DXF primitives, but
  2643. will suffice for simple objects and scenes after EXPLODE'ing and
  2644. DXFOUT'ing then in AutoCAD.
  2645.  
  2646. 8.1.3)  ShellGen
  2647.  
  2648. ShellGen is a BASIC program written by Dan Farmer.  It's based on
  2649. a short code fragment from Clifford Pickover's book "Computers,
  2650. Pattern, Chaos, and Beauty" (St. Martin's Press).  This code
  2651. fragment was reprinted in Ray Tracing News Issue 3.3.
  2652.  
  2653. As far as I know, the BASIC program only works on IBM's.  It does,
  2654. however, allow you to change the parameters and see a quick outline
  2655. of what the result will look like.
  2656.  
  2657. For those people without IBM's, I've changed the original code
  2658. fragment to at least output a DKB/PV-Ray format file.  No user
  2659. interface has been provided, however.
  2660.  
  2661. 8.1.4)  Twister
  2662.  
  2663. Twister is a C program written by Drew Wells (CIS 73767,1244).  It
  2664. creates data files for twisted shapes.  The program uses a text
  2665. interface and prompts the user with a question/answer format.
  2666.  
  2667. 8.1.5)  Chem2DKB
  2668.  
  2669. Chem2DKB is an IBM BASIC program written by Dan Farmer.  It takes
  2670. models generated by the CHEM.EXE program written by Larry Puhl.
  2671.  
  2672. 8.1.6)  Lissajou
  2673.  
  2674. This is an IBM BASIC program written by Dan Farmer.  It creates
  2675. data files for lissajous figures.  The basic algorithms were from
  2676. Clifford Pickover.  See Scientific American Jan. '91 and Omni Feb
  2677. '90 for examples.
  2678.  
  2679.  
  2680. 8.2)    Output File Manipulation Utilities
  2681.  
  2682. These utilities perform some useful manipulations on the dump
  2683. format and Targa format output files from PV-Ray.  We'd like to
  2684. thank the people who wrote these utilities and provided them for
  2685. general distribution.
  2686.  
  2687. 8.2.1)  dump2i24   (DumpToIFF24)
  2688.  
  2689. This program was written by Helge E. Rasmussen (her@compel.dk).  It
  2690. converts the dump format files produced by PV-Ray into 24-bit IFF
  2691. format files. These files can then be read by a variety of programs
  2692. including "The Art Department" by ASDG.
  2693.  
  2694. 8.2.2)  catdump
  2695.  
  2696. This utility was written by Ville Saari vsaari@niksula.hut.fi (and
  2697. copyright by the Ferry Island Pixelboys.)  It takes two or more
  2698. partially rendered files in PV-Ray's dump format and merges them
  2699. into one file.  This is useful for all sorts of things like
  2700. rendering different parts on different computers and combining the
  2701. results. 
  2702.  
  2703. NOTE:  Be careful if you combine pictures produced on different
  2704. systems.  If the random number generator works differently between
  2705. the two systems, the textures may look completely different from
  2706. one another.  So long as you use the same executable, you should be
  2707. fine.
  2708.  
  2709. 8.2.3)  combdump  (combine dump)
  2710.  
  2711. This utility was also written by Ville Saari.  It takes two images
  2712. generated with PV-Ray with slightly different viewpoints, and
  2713. creates one dump-format image file to be viewed with RED-BLUE or
  2714. RED-GREEN 3D glasses.  The program allows you to compensate for the
  2715. exact filtering characteristics of your glasses to get the best
  2716. possible result.
  2717.  
  2718. 8.2.4)  dump2mtv
  2719.  
  2720. This is yet another utility written by Ville Saari.  This one
  2721. converts PV-Ray dump format files onto MTV format used by the MTV
  2722. and RayShade raytracers.
  2723.  
  2724. 8.2.5)  dump2raw
  2725.  
  2726. The dump2raw utility was written by Aaron Collins to convert the
  2727. dump format output of PV-Ray into three separate files for red,
  2728. green, and blue.  On the IBM, the extensions for these files are
  2729. "r8", "g8", and "b8".  On the other systems, they are "red", "grn"
  2730. and "blu".
  2731.  
  2732. Version 2.10 of the raytrace allows you to use the +fr option to
  2733. output raw format files directly without the need for a conversion
  2734. program like this.
  2735.  
  2736. 8.2.6)  halftga
  2737.  
  2738. The halftga utility (written by Aaron Collins) shrinks a Targa-
  2739. format file to exactly half its original size.  This file can then
  2740. be converted into a GIF image and used in an IMAGE_MAP statement. 
  2741. For systems with little memory available for imagemaps, this
  2742. command can be a life-saver. 
  2743.  
  2744. 8.2.7)  gluetga
  2745.  
  2746. This utility (by Aaron Collins) is similar to catdump but works for
  2747. Targa format files.  It takes several partially-rendered Targa
  2748. files and glues them together into one image. 
  2749.  
  2750. 8.2.8)  tga2dump
  2751.  
  2752. This utility was written by Aaron Collins.  It converts Targa
  2753. format 16, 24, and 32 bit images into PV-Ray's dump format for use
  2754. in image-mapping.
  2755.  
  2756.  
  2757. 8.3)    Animation Utilities
  2758.  
  2759. One of the most frequent questions I'm asked is whether or not PV-
  2760. Ray supports animation.  The answer is no, not directly.  However,
  2761. I have made some changes to the program to provide frame-to-frame
  2762. consistency so you can use it for animation if you want to.  The
  2763. problem, then, is creating the data files for each individual
  2764. frame.  That's what this section is all about.
  2765.  
  2766. 8.3.1)  RayScene
  2767.  
  2768. Although RayScene is not being distributed with this raytracer, I
  2769. thought I'd at least mention it and tell you where you can get it. 
  2770. RayScene is a program that creates data files for DKB/PV-Ray based
  2771. on a high-level (higher-level?) description of the motion of the
  2772. camera and the objects.  It was written by Jari K{hk|nen
  2773. (hole@tolsun.oulu.fi) and Panu Hassi (oldfox@tolsun.oulu.fi) and is
  2774. available by anonymous FTP from tolsun.oulu.fi (128.214.5.6) in the
  2775. directory /pub/rayscene or from iear.arts.rpi.edu in the directory
  2776. /pub/graphics/ray/rayscene.
  2777.  
  2778.  
  2779. This explanation of RayScene was sent to me by Panu Hassi;
  2780.  
  2781.    "I've tried animation with DBW before DKBTrace2.0 was released. 
  2782.      The procedure was this: First I wrote the first scene file,
  2783. copied it  for NUMBER_OF_FRAMES times and then edited some parts of
  2784. those files  to create movement etc.  If something went wrong (I
  2785. accidentally edited  wrong value etc), I had to edit all those
  2786. scene files again to make the changes.  Not so nice if there are
  2787. 100 files to edit...     
  2788.     So a friend of mine, Jari K{hk|nen, and I decided to write
  2789. RayScene to make that process even a little easier.  With RayScene
  2790. the process goes like this:  you create a scene file and mark the
  2791. places that should be changed with a variable, like:
  2792.  
  2793.     BOUNDED_BY                              
  2794.          SPHERE <0.0 0.0 0.0> #sphere_size# END_SPHERE
  2795.     END_BOUND
  2796.     
  2797.     Then you create another file where the values for these
  2798. variables are listed.  Rayscene simply creates N scene files
  2799. inserting current value of each variable to proper place.  That's
  2800. all :D
  2801.     
  2802.     We have included couple of simple utilities that help with
  2803. creating  those variable values, but the original scene files are
  2804. still created  'manually'.  Still, the results have been really
  2805. nice.  There are several animations for Amiga and PC in
  2806. tolsun.oulu.fi."
  2807.  
  2808. 9)  How it All Works (or How to Get What You Want)
  2809.  
  2810. The information in this section is designed for people who are
  2811. reasonably familiar with the raytracer and want more information on
  2812. how things work so they can push it to its limits.  You probably
  2813. don't need this level of detail to make interesting data files, but
  2814. if you suddenly get confused about something the program did, this
  2815. section may help you figure it out.
  2816.  
  2817. 9.1)    Viewpoints
  2818.  
  2819. Viewpoints can be completely defined by four vectors.  The LOCATION
  2820. is easy. That's where the camera is.  The DIRECTION is a vector
  2821. that starts at the LOCATION and points to the center of a window. 
  2822. The UP vector starts at the center of the window and points to the
  2823. center of the top edge.  The RIGHT vector starts at the center of
  2824. the window and points to the center of the right edge. 
  2825.  
  2826.                               |\
  2827.                               | \
  2828.                               |  \
  2829.                               |   \
  2830.                               |  ^ \
  2831.                               |  |Up|
  2832.                               |  |  |
  2833.                               |  |  |
  2834.     Location *------------------->  |
  2835.                 Direction     |   \ |Right
  2836.                               |    \|
  2837.                               \     |
  2838.                                \    |
  2839.                                 \   |
  2840.                                  \  |
  2841.                                   \ |
  2842.                                    \|
  2843.  
  2844. The window is then divided up according to the resolution you
  2845. specified and rays are fired through the pixels out into the world. 
  2846. For an eye ray, therefore, the equation of the ray is:
  2847.  
  2848.    Location + t (Direction + ((height - y)*UP) + (x*RIGHT))
  2849.  
  2850. where "t" is a parameter that determines the distance from the eye
  2851. to the object being tested.  The Y coordinate is inverted by
  2852. subtracting it from height because most graphics systems put 0,0 in
  2853. the top left corner of the screen.
  2854.  
  2855. This viewpoint model is very flexible.  It allows you to use left-
  2856. handed or right-handed coordinate systems.  It also doesn't require
  2857. that the DIRECTION, UP, and RIGHT vectors be mutually orthogonal. 
  2858. If you want, you can distort the camera to get really bizarre
  2859. results.
  2860.  
  2861. Once the basic four vectors are specified, it's possible to use the
  2862. SKY and LOOK_AT vectors to point the camera.  You must specify the
  2863. SKY vector first, but let me describe the LOOK_AT vector first. 
  2864. LOOK_AT tells the camera to rotate in such a way that the LOOK_AT
  2865. point appears in the center of the screen.  To do this, the camera
  2866. first turns in the left-to-right direction (longitude in Earth
  2867. coordinates) until it's lined up with the LOOK_AT point. It then
  2868. turns in the up/down direction (latitude in Earth coordinates)
  2869. until it's looking at the desired point.
  2870.  
  2871. Ok, now we're looking at the proper point.  What else do we have to
  2872. specify? If you're looking at a point, you can still turn your
  2873. camera sideways and still be looking at the same spot.  This it the
  2874. orientation that the SKY direction determines.  The camera will try
  2875. to position itself so that the camera's UP direction lines up as
  2876. closely as possible to the SKY direction.
  2877.  
  2878. Put another way - in airplane terms, the LOOK_AT vector determines
  2879. your heading (north, south, east, or west), and your pitch
  2880. (climbing or descending).  The SKY vector determines your banking
  2881. angle.
  2882.  
  2883. 9.2)    Ray-Object Intersections
  2884.  
  2885. For every pixel on the screen, the raytracer fires at least one ray
  2886. through that pixel into the world to see what it hits.  For each
  2887. hit (well, almost), it calculates rays to each of the light sources
  2888. to see if that point is shadowed from that light source.  For
  2889. reflecting objects, a reflected ray is traced.  For refracting
  2890. objects, a refracting ray is traced.  That all adds up to a lot of
  2891. rays.
  2892.  
  2893. Every ray is tested against every object in the world to see if the
  2894. ray hits that object. This is what slows down the raytracer.  You
  2895. can make things easier by using simple bounding shapes on your
  2896. objects.
  2897.  
  2898.  
  2899. 9.3)    Transparency and Refraction
  2900.  
  2901. This section get really complicated because of the way transparency
  2902. and refraction are implemented.  If you don't really care, skip to
  2903. the next section. If you don't mind slogging through this and
  2904. getting confused, then read on.
  2905.  
  2906. - you've been warned -
  2907.  
  2908. The way that transparency and refraction work has changed slightly
  2909. from previous versions.  Now, transparency and refraction work
  2910. together instead of separately.
  2911.  
  2912. First, let me distinguish between reflected light and filtered
  2913. light.  Suppose you painted a table with patches of colour.  You
  2914. then took some red sand and sprinkled it on top of the various
  2915. colours.  The red sand will tint the colours red, but you will
  2916. still see some of the original colour.  If, instead, you took a
  2917. sheet of red plexiglass and put it on top of the table, all you
  2918. could see would be shades of red.  That's because the plexiglass
  2919. filter ONLY allows the red colour to show through.
  2920.  
  2921. In PV-Ray, the layered textures work like the red sand - the
  2922. colours on top mix with the underlying colours depending on the
  2923. density (ALPHA) of the distribution.
  2924.  
  2925. Refraction, however, works like a filter.  The surface colour
  2926. determines that colours of light are allowed to pass from the
  2927. inside of the object to the outside, and vice versa.  Here are some
  2928. filter colours:
  2929.  
  2930.    RED 1.0  GREEN 0.0  BLUE 0.0   ALPHA 1.0    - a red filter     
  2931.    RED 1.0  GREEN 1.0  BLUE 1.0   ALPHA 1.0    - clear glass    
  2932.    RED 0.0  GREEN 0.0  BLUE 0.0   ALPHA 1.0    - a dark filter 
  2933.                                                - this will        
  2934.                                                  appear black.
  2935.  
  2936. Now, consider the following layered textures:
  2937.  
  2938.    TEXTURE COLOUR Green ALPHA 0.6 END_TEXTURE
  2939.    TEXTURE COLOUR Yellow ALPHA 0.3 REFRACTION 0.5 END_TEXTURE
  2940.  
  2941. (Keep in mind that the last texture is on top.)
  2942.  
  2943. NOTE: In layered textures, only the REFRACTION component of the
  2944. LAST entry has any effect.
  2945.  
  2946. The colour you get is calculated like this:
  2947.  
  2948.          ____  Full Brightness
  2949.          |
  2950.          |
  2951.          |
  2952.          |
  2953.          |
  2954.          |   7/10 of pixel's colour is Yellow
  2955.          |
  2956.          |
  2957.          |
  2958.          |
  2959.          |
  2960.          |---
  2961.          |    
  2962.       -  |   3/10 (alpha) left over for underlying colour
  2963.      |   |
  2964.      |   |
  2965.      |   ----  Full Darkness
  2966.      |
  2967.      |
  2968.      |
  2969.      |
  2970.      |   ____  From the 3/10 available:
  2971.      |   |
  2972.      |   |
  2973.      |-> |   4/10 is green
  2974.          |
  2975.          |
  2976.          |---6/10 (alpha) is available for refraction
  2977.          |
  2978.          |
  2979.          |
  2980.          |
  2981.          |-- 5/10 of that (6/10) is passed through from refraction 
  2982.          |        and filtered by the combined filter colour      
  2983.          |        (yellow filtered by green).
  2984.          |
  2985.          |
  2986.          |
  2987.          ----
  2988.  
  2989.  
  2990. So, the top texture layer supplies some fraction of the light that
  2991. reflects off the surface of the object.  If the ALPHA was non-zero,
  2992. it allows the lower  textures to supply the remainder.  If, after
  2993. all the textures are processed, there's still some fraction left
  2994. over, it is applied to the light that's refracted through the
  2995. object.
  2996.  
  2997. This algorithm probably doesn't coincide with reality, but neither
  2998. does the rest of the raytracer, so I'm not terribly concerned about
  2999. it.
  3000.  
  3001. 9.4)    Textures, Noise, and Turbulence
  3002.  
  3003. If there's one thing that PV-Ray is known for, it's textures. 
  3004. Here's how they really work.  If you want some good reading
  3005. material, check out "An Image Synthesizer" by Ken Perlin in the
  3006. SIGGRAPH '84 Conference Proceedings.
  3007.  
  3008. Let's start with a marble texture.  Real marble is created when
  3009. different colours of sediments are laid down one on top of another
  3010. and compressed to form solid rock.
  3011.  
  3012. For example, take a simple block of marble:
  3013.           ___________
  3014.          /          /|
  3015.         /          / |
  3016.        /__________/  |
  3017.        |   Red    | /|
  3018.        |----------|/ |
  3019.        |  White   | /|
  3020.        |----------|/ |
  3021.        |   Red    | /|
  3022.        |----------|/ |
  3023.        |  White   | /
  3024.        |__________|/
  3025.  
  3026. If you carve a shape put of this block of marble, you will get red
  3027. and white bands across it.
  3028.  
  3029. Now, consider wood.  The rings in wood are created when the tree
  3030. grows a new outer shell every year.  Hence, we have concentric
  3031. cylinders of colours:
  3032.  
  3033.                 ______
  3034.                /      /
  3035.               /      / \
  3036.              /      /   \
  3037.             /      /     \
  3038.            /      /      |
  3039.           /______/       |
  3040.          / _____ \       |
  3041.         / / ___ \ \      |
  3042.        / / / _ \ \ \     /    (how do you draw a log in ASCII??!!) 
  3043.      / / / / \ \ \ \   /
  3044.       | | | | | | | |  /
  3045.       | | | |O| | | | /
  3046.       | | | | | | | |/
  3047.       \ \ \ \_/ / / /
  3048.        \ \ \___/ / /
  3049.         \ \_____/ /
  3050.          \_______/
  3051.  
  3052. Cutting a shape out of a piece of wood will tend to give you rings
  3053. of colour.
  3054. Now, this is fine, but the textures are still a bit boring.  For
  3055. the next step, we blend the colours together to create a nice
  3056. smooth transition.  This makes the texture look a bit better.  The
  3057. problem, though, is that it's too regular - real marble and wood
  3058. aren't so perfect.
  3059.  
  3060. Before we make our wood and marble look any better, let's look at
  3061. how we make noise.  Noise (in raytracing) is sort of like a random
  3062. number generator, but it has the following properties:
  3063.  
  3064.    1) It's defined over 3D space i.e., it takes x, y, and z and
  3065. returns the       noise value there.
  3066.    2) If two points are far apart, the noise values at those points
  3067. are       relatively random.
  3068.    3) If two points are close together, the noise values at those
  3069. points are       close to each other.
  3070.  
  3071. You can visualize this as having a large room and a thermometer
  3072. that ranges from 0.0 to 1.0.  Each point in the room has a
  3073. temperature.  Points that are far apart have relatively random
  3074. temperatures.  Points that are close together have close
  3075. temperatures. The temperature changes smoothly, but randomly as we
  3076. move through the room.
  3077.  
  3078. Now, let's place an object into this room along with an artist. 
  3079. The artist measures the temperature at each point on the object and
  3080. paints that point a different colour depending on the temperature. 
  3081. What do we get?  BOZO texture!
  3082.  
  3083. Another function used in texturing is called DNoise.  This is sort
  3084. of like noise except that instead of giving a temperature, it gives
  3085. a direction.  You can think of it as the direction that the wind is
  3086. blowing at that spot.
  3087.  
  3088. Finally, we have a function called turbulence which uses DNoise to
  3089. push a particle around a few times - each time going half as far as
  3090. before.
  3091.  
  3092.          P ------------------------->
  3093.                   First Move        /
  3094.                                    /
  3095.                                   /
  3096.                                  /Second
  3097.                                 /  Move
  3098.                                /
  3099.                         ______/
  3100.                         \
  3101.                          \
  3102.                           \
  3103.                            Q - Final point.
  3104.  
  3105. This is what we use to create the "interesting" marble and wood
  3106. texture.  We locate the point we want to colour (P), then push it
  3107. around a bit using Turbulence to get to a final point (Q) then look
  3108. up the colour of point Q in our ordinary boring wood and marble
  3109. textures.  That's the colour that's used for the point P.
  3110.  
  3111.  
  3112. 9.5)    Layered Textures
  3113.  
  3114. PV-Ray supports layered textures.  Here's how that works.
  3115.  
  3116. Each object and each shape has a texture that may be attached to
  3117. it.  By default, shapes have no texture, but objects have a default
  3118. texture. Internally, textures are marked as being constant or
  3119. variable.  A constant texture is one that was DECLAREd as a texture
  3120. and is being shared by many shapes and objects.  Variable textures
  3121. are textures that have been declared totally within the object or
  3122. have used a DECLAREd texture and modified it in a destructive way. 
  3123. The idea here is that we want to save on memory by sharing textures
  3124. if possible. 
  3125.  
  3126. If you have several texture blocks for an object or a shape, they
  3127. are placed into a linked list (First-in Last-out).  For example,
  3128. take the following definition:
  3129.  
  3130.    OBJECT
  3131.       SPHERE <0 0 0> 1 END_SPHERE
  3132.       TEXTURE WOOD END_TEXTURE
  3133.       TEXTURE MARBLE END_TEXTURE
  3134.    END_OBJECT
  3135.  
  3136. Here's what happens while parsing this object:  Since this is an
  3137. object (as opposed to a shape - SPHERE, PLANE, etc.), it starts out
  3138. with the default texture attached.
  3139.  
  3140.    ________      _________
  3141.    |      |      |       |
  3142.    |      |----->|Default|
  3143.    |Object|      |Texture|
  3144.    |      |      |_______|
  3145.    |      |
  3146.    |______|
  3147.  
  3148. When the parser sees the first TEXTURE block, it looks to see what
  3149. it has linked.  Since the thing that's linked is the default
  3150. texture (not a copy), it discards it and puts in the new texture.
  3151.  
  3152.    ________      _________
  3153.    |      |      |       |
  3154.    |      |----->| WOOD  |
  3155.    |Object|      |Texture|
  3156.    |      |      |_______|
  3157.    |      |
  3158.    |______|
  3159.  
  3160. On the next texture, it sees that the texture isn't the default
  3161. one, so it adds the second texture into the linked list.
  3162.    ________      _________      _________
  3163.    |      |      |       |      |       |
  3164.    |      |----->|MARBLE |----->| WOOD  |
  3165.    |Object|      |Texture|      |Texture|
  3166.    |      |      |_______|      |_______|
  3167.    |      |
  3168.    |______|
  3169.  
  3170.  
  3171. Now for a problem.  If you want to specify the REFRACTION of the
  3172. texture, the raytracer must first calculate the surface colour.  It
  3173. does this by marching through the texture list and mixing all the
  3174. colours.  When it's finished, it checks the ALPHA value of the
  3175. surface colour and decides whether it should trace a refracting
  3176. ray.  Where does it get the REFRACTION value and the index of
  3177. refraction?  It simply takes the one in the topmost (the last one
  3178. defined) texture.  I don't see any reason to have refraction values
  3179. for any other textures in the layer as it applies to the whole
  3180. object.
  3181.  
  3182. 9.6)    Image Mapping
  3183.  
  3184. One major problem people have when designing data files for PV-Ray
  3185. is how to position images onto the desired surfaces.  With the
  3186. latest version, this problem becomes slightly easier since the
  3187. image can be mapped onto the object in the object's natural
  3188. coordinate system.  Thereafter, when the object is translated,
  3189. rotated, or scaled, the image map will follow it.
  3190.  
  3191. One form of image mapping that PV-Ray supports is called a
  3192. "parallel projection" mapping.  This technique is simple (that's
  3193. why I implemented it :-), but it's not perfect.  It works like a
  3194. slide projector casting the desired image onto the scene.  The
  3195. difference, however, is that the image never gets larger as you
  3196. move further away from the slide projector.  In fact, there is no
  3197. real slide projector.  Consider the following cross section:
  3198.  
  3199. ***Sorry formatting is twisted on this one! ***
  3200. Image to Map
  3201.     |                 _________
  3202.     V                 \       /            /\       
  3203. ___________________                        \     /            /  \ 
  3204.      \                 / ----A-------------------A   A------------A 
  3205.   A-------A---------------A-->     B                    B B       
  3206.     B      B       BB           BB     C                     C    
  3207.        C        C        CCCC   CCCC     D                        
  3208.         D          D           DDD     E                          
  3209.      E            E
  3210.     F                               F              F
  3211. ----G------------------------------G                G--------------
  3212. ------>                                   /                  \
  3213.                                  /____________________\
  3214.  
  3215. This two dimensional example shows an image with colours
  3216. A,B,C,D,E,F, and G being mapped onto three objects.  The raytracer
  3217. performs a similar operation to map a 2D picture onto a 3D object. 
  3218. Note that objects cannot shadow each other from the image being
  3219. mapped.  This means that the image will also appear on the back of
  3220. the object as a mirror image.
  3221.  
  3222. The mapping takes the original image (regardless of the size) and
  3223. maps it onto the range 0,0 to 1,1 in two of the 3D coordinates. 
  3224. Which two coordinates is specified by the gradient vector provided
  3225. after the image.  This vector must contain one positive number, one
  3226. negative number, and one zero.  The positive number identifies the
  3227. u axis (the left-right direction in the image) and the negative
  3228. number represents the v axis (the picture's up-down direction). 
  3229. Note that the magnitude of the number is irrelevant.
  3230.  
  3231. For example:
  3232.  
  3233.     IMAGEMAP <1 -1 0> GIF "filename" END_MAP
  3234.  
  3235. will map the GIF picture onto the square from <0 0 0> to <1 1 0>
  3236. like this:
  3237.  
  3238.         Y
  3239.         ^
  3240.         |
  3241.         |
  3242.         |          
  3243.       1 |----------
  3244.         |   Top  R|
  3245.         |L       i|
  3246.         |e       g|
  3247.         |f       h|
  3248.         |t       t|
  3249.         | Bottom  |
  3250.         ----------------> X
  3251.                   1
  3252.  
  3253. If we reversed the vector, the picture would be transposed:
  3254.  
  3255.     IMAGEMAP <-1 1 0> GIF "filename" END_MAP
  3256.  
  3257. produces:
  3258.  
  3259.         Y
  3260.         ^
  3261.         |
  3262.         |
  3263.         |          
  3264.       1 |----------
  3265.         |B Right  |
  3266.         |o       T|
  3267.         |t       o|
  3268.         |t       p|
  3269.         |o        |
  3270.         |m  Left  |
  3271.         ----------------> X
  3272.                   1
  3273.  
  3274. Once the image orientation has been determined, it can be
  3275. translated, rotated, and scaled as desired to map properly onto the
  3276. object.
  3277.  
  3278.  
  3279.  
  3280. 9.7)    Output File Formats
  3281.  
  3282. People always ask me to describe the output file formats of PV-Ray. 
  3283. I received so many requests for this that I decided to put it into
  3284. the document.
  3285.  
  3286. The normal "default" output format is "dump" format.  This is based
  3287. on QRT format and goes like this, where each character is a hex
  3288. digit:
  3289. Header:
  3290.      wwww hhhh          - width, height (16 bits each, LSB first)
  3291.  
  3292. For each data line:
  3293.      llll               - line number (16 bits, LSB first, 0 to   
  3294.                           LINES-1)      
  3295. rr rr rr rr rr ...      - the red components for that line
  3296.                           (8 bits each - 0=dark, 255=bright)
  3297.  
  3298.      gg gg gg gg gg ... - the green components for that line      
  3299.                           (8 bits each - 0=dark, 255=bright)
  3300.  
  3301.      bb bb bb bb bb ... - the blue components for that line       
  3302.                           (8 bits each - 0=dark, 255=bright)
  3303.  
  3304. Note that this format is slightly different from QRT's.
  3305.  
  3306.  
  3307. The "+fr" option of the raytracer produces "raw" files.  These are
  3308. simply three files with no header information and no line number
  3309. information - just the raw data.
  3310.  
  3311. The "+ft" option writes out Targa format.  Specifically, the fields
  3312. are:
  3313.  
  3314. Header:
  3315.    00 00 02 00 00      - Fixed header information for uncompressed
  3316. type 2 image    
  3317.    00 00 00
  3318.    0000                - Horizontal offset always is at 0000      
  3319.    llll                - Vertical offset (1st line number, 16 bits, 
  3320.                          LSB first)    
  3321.    wwww hhhh           - width, height of image (16 bits each, LSB 
  3322.                          first)    
  3323.    18 20               - 24 bits per pixel, Top-down raster
  3324.  
  3325. For each line:
  3326.    bb gg rr bb gg rr ... - blue, green, and red data, 8 bits for
  3327. each pixel.
  3328.  
  3329.  
  3330.  
  3331.  
  3332. 10) Common Questions and Answers
  3333.  
  3334. I often get asked the same questions again and again.  I usually
  3335. take this to mean that the documentation is not complete or not
  3336. sufficiently clear.  In order to correct this problem, I've added
  3337. some sections to the document describing the features in more
  3338. detail.  I've also collected some of the more popular questions and
  3339. answered them here:
  3340.  
  3341.  
  3342.  Q: I defined a light source but the shadows and lighting are all
  3343. wrong.      
  3344. A: Light sources must be defined at the origin (0,0,0) and
  3345. translated to  the proper place.  The reason for this is to allow
  3346. the diffuse lighting calculations to quickly determine where the
  3347. center of the light source is.  It's a very difficult task to
  3348. calculate the center of an object  (in general), so I simply take
  3349. the place that the object was translated to as the center of the
  3350. light source.
  3351.  
  3352.  Q: I keep running out of memory.  What can I do?
  3353.      
  3354. A: Buy more memory :-)  But seriously, you can decrease the memory 
  3355.        requirements for any given picture in several ways:        
  3356.   1) DECLARE texture constants and use them (textures are shared). 
  3357.   2) Don't modify the texture that you are sharing.  On the first 
  3358.      modify, the texture is copied and (therefore) takes up more  
  3359.      space.           
  3360.   3) Put the object transformations before the texture structure. 
  3361.      This prevents the texture from being transformed (and hence, 
  3362.      copied. This may not always be desirable, though).
  3363.   4) Use UNIONS instead of COMPOSITE objects to put pieces        
  3364.      together. (previous versions of the raytracer didn't allow   
  3365.      this because the texture applied to the entire object.       
  3366.      Version 2.10 and up allow you to change the texture on a per- 
  3367.      shape basis.)
  3368.    5) Use fewer or smaller image maps.
  3369.    6) Use GIF or IFF (non-HAM) images for image maps.  These are s 
  3370.       tored internally as 8 bits per pixel with a colour table    
  3371.       instead of 24 bits per pixel.
  3372.           
  3373. Q: I get a floating point exception error on certain pictures.    
  3374.    What's wrong?
  3375. A: Oh no! The raytracer performs many thousands of
  3376.   floating point operations when tracing a scene.  If checks were
  3377. added to each one for overflow or underflow, the program would be
  3378. much longer If you get this problem, I'd suggest that you       
  3379. first look through your data file to make sure you're not doing   
  3380. something like:
  3381.  
  3382.           - Scaling something by 0.0 in ANY dimension
  3383.           - Making the LOOK_AT point the same as the LOCATION     
  3384.      - Defining triangles with two points the same (or nearly the
  3385. same)           
  3386.      - Using the zero vector for normals.
  3387.  
  3388.         If it doesn't seem to be one of these problems, please let
  3389. us know. If you do have such troubles, you can try to isolate the 
  3390. problem in the input data file by commenting out objects or groups 
  3391. of objects until you narrow it down to a particular section that  
  3392. fails.  Then try commenting out the individual characteristics of
  3393. the offending object.
  3394.  
  3395.      Q: No matter how much I scale a Cylinder, I can't make it fit
  3396. on the screen.  How big is it and how much do I have to scale it? 
  3397.     A: Cylinders (like most quadrics) are infinitely long.  No
  3398. matter how much you scale them, they still won't fit on the screen. 
  3399. To make a capped cylinder, you must use CSG:
  3400.  
  3401.            INTERSECTION
  3402.               QUADRIC Cylinder_Y END_QUADRIC
  3403.               PLANE <0.0 1.0 0.0> 1.0 END_PLANE
  3404.               PLANE <0.0 -1.0 0.0> 1.0 END_PLANE
  3405.            END_INTERSECTION
  3406.  
  3407.         Cylinders CAN be scaled in cross-section, the two vectors
  3408. NOT in the  name of the cylinder (X and Z, in our example above)
  3409. can be scaled to control the width and thickness of the cylinder. 
  3410. Scaling the Y value (which is normally infinite) is meaningless,
  3411. unless you have "capped" it as above, then scaling the entire
  3412. INTERSECTION object in the Y dimension will control the height of
  3413. the cylinder.
  3414.  
  3415.      Q: Why isn't there a primitive for a 6-sided box?
  3416.      A: Because you can do it so easily with CSG:
  3417.         Also, see cube in textures.dat    
  3418.            INTERSECTION
  3419.               PLANE < 1.0  0.0  0.0> 1.0 END_PLANE
  3420.               PLANE <-1.0  0.0  0.0> 1.0 END_PLANE
  3421.               PLANE < 0.0  1.0  0.0> 1.0 END_PLANE
  3422.               PLANE < 0.0 -1.0  0.0> 1.0 END_PLANE
  3423.               PLANE < 0.0  0.0  1.0> 1.0 END_PLANE
  3424.               PLANE < 0.0  0.0 -1.0> 1.0 END_PLANE
  3425.            END_INTERSECTION
  3426.  
  3427.      Q: Are planes 2D objects or are they 3D but infinitely thin? 
  3428.     A: Neither.  Planes are 3D objects that divide the world into
  3429. two half-spaces.  The space in the direction of the surface normal
  3430. is considered outside and the other space is inside. In other
  3431. words, planes are 3D objects that are infinitely thick.
  3432.                             ^
  3433.                             |
  3434.                             |
  3435.                             |  Outside
  3436.                      _______|_______
  3437.                                Inside
  3438.      Q: Can PV-Ray render soft shadows?
  3439.      A: Not yet. You can place an unturbulated WOOD texture       
  3440.  "filter" over a lamp in a can, and use a colour map going from
  3441. dark  (ALPHA 0.0) around the edges to clear (ALPHA 1.0) at the
  3442. center,  and get a soft-shadow-like effect for a "spotlight".
  3443.  
  3444.      Q: I'd like to go through the program and hand-optimize the
  3445. assembly code  in places to make it faster.  What should I
  3446. optimize?  
  3447. A: Don't bother.  With hand optimization, you'd spend a lot of time
  3448. to  get perhaps a 5-10% speed improvement at the cost of total loss
  3449. of portability.  If you use a better ray-surface intersection
  3450. algorithm, you should be able to get an order of magnitude or more
  3451. improvement. Check out some books and papers on raytracing for
  3452. useful techniques.Specifically, check out "Spatial Subdivision" and
  3453. "Ray Coherence" techniques.
  3454.  
  3455.      Q: Objects on the edges of the screen seem to be distorted. 
  3456. Why? 
  3457. A: If the DIRECTION vector of the viewpoint is not very long, you
  3458. may get distortion at the edges of the screen.  The reason for this
  3459. is that the viewpoint's screen is flat:
  3460.  
  3461.  
  3462.                                | /\  This object looks small      
  3463.                                | \/
  3464.                                |
  3465.                                |
  3466.                                *   <---- * = Projection of objects
  3467. onto screen.                   |
  3468.                                |
  3469.                Viewpoint --> V * /\  This object looks big
  3470.                                * \/
  3471.                                |
  3472.                                |
  3473.                                |
  3474.                                |<---- viewing screen.
  3475.                                |
  3476.                                |
  3477.  
  3478. Q: How do you position planar image maps without a lot of trial and
  3479. error?      
  3480. A: By default, images will be mapped onto the range 0,0 to 1,1 in
  3481. the appropriate plane.  You should be able to translate, rotate,
  3482. and scale the image from there.
  3483.  
  3484. Q: What's the difference between ALPHA and REFRACTION?      
  3485. A: The difference is a bit subtle.  Alpha is a component of a
  3486. colour that determines how much light can pass through that colour. 
  3487. Refraction is a property of a surface that determines how much
  3488. light can come from inside the surface.  See the section above on
  3489. Transparency and  Refraction for more details.
  3490.  
  3491.      Q: How do you calculate the surface normals for smooth
  3492. triangles?      
  3493. A: When I implemented smooth triangles, I never really expected
  3494. anyone to  manually calculate the surface normals.  There are two
  3495. ways of getting  another program to calculate them for you. There
  3496. are now several utilities to help with this.
  3497.  
  3498.           1) Depending on the type of input to the program, you may
  3499. be able to  calculate the surface normals directly.  For example,
  3500. if you have a program that converts B-Spline or Bezier Spline
  3501. surfaces into PV-Ray-format files, you can calculate the surface
  3502. normals from the  surface equations.
  3503.  
  3504.           2) If your original data was a polygon or triangle mesh,
  3505. then it's  not quite so simple.  You have to first calculate the
  3506. surface normals of all the triangles.  This is easy to do - you
  3507. just use the vector cross-product of two sides (make sure you get
  3508. the vectors in the right order).  Then, for every vertex, you
  3509. average the surface normals of the triangles that meet at that
  3510. vertex. These are the normals you use for smooth triangles. See
  3511. utility SANDPAPER.
  3512.  
  3513.      Q: When I render parts of a picture on different systems, the
  3514. textures don't match when I put them together.  Why?
  3515.      A: The appearance of a texture depends on the particular
  3516. random number generator used on your system.  PV-Ray seeds the
  3517. random number generator with a fixed value when it starts, so the
  3518. textures will be consistent from one run to another or from one
  3519. frame to another so long as you use the same executables.  Once you
  3520. change executables, you will likely change the random number
  3521. generator and, hence, the appearance of the texture.  There is an
  3522. example of a standard ANSI  random number generator provided in
  3523. IBM.C, include it in your machine-specific code if you are having
  3524. consistency problems.
  3525.  
  3526.      Q: What's the difference between a COLOUR declared inside a
  3527. TEXTURE and one that's in a shape or an object and not in a
  3528. texture?      
  3529. A: The colour in the texture specifies the colour to use for
  3530. qualities 5 and up.  The colour on the shape and object are used
  3531. for faster rendering in qualities 4 and lower and for the colour of
  3532. light sources. See the -q option for details on the quality
  3533. parameter.
  3534.  
  3535.  
  3536.      Q: I created an object that passes through its bounding
  3537. volume.  At times, I can see the parts of the object that are
  3538. outside the bounding volume.Why does this happen?
  3539.      A: Bounding volumes are not designed to change the shape of
  3540. the object. They are strictly a realtime improvement feature.  The
  3541. raytracer trusts you when you say that the object is enclosed by a
  3542. bounding volume.  The way it uses bounding volumes is very simple: 
  3543. If the ray hits the bounding volume (or the ray's origin is inside
  3544. the bounding volume),when the object is tested against that ray. 
  3545. Otherwise, we ignore the object.  If the object extends beyond the
  3546. bounding volume, anything goes. The results are undefined.  It's
  3547. quite possible that you could see the object outside the bounding
  3548. volume and it's also possible that it could be invisible.  It all
  3549. depends on the geometry of the scene. If you want this effect use
  3550. a CLIPPED_BY volume instead of BOUNDED_BY
  3551.  
  3552.      Q: Will PV-Team be writing a Graphical User Interface for PV-
  3553. Ray?      
  3554.      A: Yes, it's in development now.
  3555.         
  3556.      
  3557.  
  3558. 11) Converting Data Files from DKB 2.12 to PV-Ray BETA 0.5
  3559.    See the program and doc CNVDAT.
  3560.  
  3561. 12) Handy Hints
  3562.  
  3563.      - To see a quick version of your picture, use -w64 -h80 as
  3564. command line parameters on the Amiga.  For the IBM, try -w80 -h50. 
  3565. This  displays the picture in a small rectangle so that you can see
  3566. how it will look.
  3567.  
  3568.      -  Try using the sample default files for different usages -
  3569. QUICK.DEF shows a fast postage-stamp rendering (80x50, as above) to
  3570. the screen only, LOCKED.DEF will display the picture with anti-
  3571. aliasing  on (takes forever) with no abort (do this before you go
  3572. to bed...). The normal default options file PVRAY.DEF is read and
  3573. you can supersede this with another .DEF file by specifying it on
  3574. the command line, for example:
  3575.  
  3576.           pvray -iworld.dat -oworld.out quick.def
  3577.  
  3578.      -    When translating light sources, translate the OBJECT, not
  3579. the QUADRIC surface.  The light source uses the center of the
  3580. object as  the origin of the light.
  3581.  
  3582.      - When animating objects with solid textures, the textures
  3583. must move with the object, i.e. apply the same ROTATE or TRANSLATE
  3584. functions to the texture as to the object itself.  This is now done
  3585. automatically if the transformations are placed _after_ the TEXTURE
  3586. block.
  3587.  
  3588.      -  You can declare constants for most of the data types in the
  3589. program including floats and vectors.  By combining this with
  3590. INCLUDE files, you can easily separate the parameters for an
  3591. animation into a  separate file.
  3592.  
  3593.      -    The amount of ambient light plus diffuse light should be
  3594. less than or equal to 1.0.  The program accepts any values, but may
  3595. produce  strange results.
  3596.  
  3597.      -    When using ripples, don't make the ripples too deep or
  3598. you may get strange results (the dreaded "digital zits"!).
  3599.  
  3600.      -    Wood textures usually look better when they are scaled to
  3601. different values in x, y, and z, and then rotated to a different
  3602. angle.
  3603.  
  3604.      -    You can compensate for non-square aspect ratios on the
  3605. monitors by  making the RIGHT vector equal to (pixel width/pixel
  3606. height). On an IBM-PC VGA that is (640/480)=1.333.  A good value
  3607. for the Amiga & IBM-PC is about 1.333. If your spheres and circles
  3608. aren't round, try varying it.
  3609.  
  3610.      -    If you are importing images from other systems, you may
  3611. find that the shapes are backwards (left-to-right inverted) and no
  3612. rotation  can make them right.  All you have to do is negate the
  3613. terms in the  RIGHT vector of the viewpoint to flip the camera
  3614. left-to-right (use the "right-hand" coordinate system).
  3615.  
  3616.      -    By making the DIRECTION vector in the VIEWPOINT longer,
  3617. you can  achieve the effect of a tele-photo lens.
  3618.  
  3619.      -    When rendering on the Amiga, use a resolution of 320 by
  3620. 400 to  create a full sized HAM picture.
  3621.  
  3622.  
  3623.  
  3624. 13) Compiling the Code
  3625.  
  3626. If you want to compile the source code on a supported platform, do
  3627. the following:
  3628.  
  3629.     1) Copy or rename the file called <system>conf.h to config.h  
  3630.        eg.  rename amigaconf.h config.h
  3631.  
  3632.     2) Copy or rename the appropriate make file to "makefile"     
  3633.     eg.  rename amigamake makefile
  3634.  
  3635.     3) Edit the makefile to make sure all compiler options are set 
  3636.       up properly for your system.
  3637.  
  3638.     4) Type "make"
  3639.  
  3640. 14) Porting to Different Platforms
  3641.  
  3642. We've taken great pains to make PV-Ray as portable as possible.  So
  3643. far, it's working out fairly well.  For the most part, the core of
  3644. the raytracer will compile with any decent C compiler.
  3645.  
  3646. If you want to port the raytracer to another system, please try to
  3647. modify the core of the raytracer as little as possible.  Each
  3648. system will have its own makefile, config file, and C file.  The
  3649. config file is included by all of the raytrace modules and can be
  3650. used to perform special #defines for that system. The C file should
  3651. contain all system-specific code.  It must implement the following
  3652. functions:
  3653.  
  3654.    void display_init ();    /* Open the graphics device and
  3655. initialize it */    void display_close();    /* Close the graphics
  3656. device                  */    void display_finished(); /* Perform
  3657. any operations required after      */                            
  3658. /* finishing the rendering but before quitting*/    void
  3659. display_plot (x, y, Red, Green, Blue)
  3660.                             /* Display the specified colour at
  3661. point x,y  */
  3662.  
  3663.  
  3664. In your config file, you may customize the following things:
  3665.  
  3666.    #define FILE_NAME_LENGTH    (default 150)
  3667.    #define DBL_FORMAT_STRING   (the string to use to read a double) 
  3668.   #define DEFAULT_OUTPUT_FORMAT ('d', 'r' or 't' - default output
  3669. file format)    #define TEST_ABORT          (the operation to
  3670. perform while tracing to see                                 if we
  3671. should abort the trace.)    #define RED_RAW_FILE_EXTENSION
  3672.    #define GREEN_RAW_FILE_EXTENSION
  3673.    #define BLUE_RAW_FILE_EXTENSION
  3674.                                (the default extensions for the +fr
  3675. mode)
  3676.  
  3677.    #define STARTUP_PV_RAY   (the code to call immediately after
  3678. starting                                 the main program. - useful
  3679. if you don't have                                 a command-line
  3680. interface)
  3681.  
  3682.    #define PARAMS(x)           ("(x)" if you have prototypes, "()"
  3683. otherwise)
  3684.  
  3685.  
  3686.  
  3687. 15) References
  3688.  
  3689. I'm always asked about good books on raytracing and graphics in
  3690. general. This section address that issue by listing several good
  3691. books or periodicals that you should be able to locate in your
  3692. local computer book store or your local university library.
  3693.  
  3694.     "An Introduction to Raytracing"
  3695.     Andrew S. Glassner (editor)
  3696.     Academic Press
  3697.     1989
  3698.  
  3699.     "Image Synthesis:  Theory and Practice"
  3700.     Nadia Magnenat-Thalman and Daniel Thalmann
  3701.     Springer-Verlag
  3702.     1987
  3703.  
  3704.     "The RenderMan Companion"
  3705.     Steve Upstill
  3706.     Addison Wesley
  3707.     1989
  3708.  
  3709.     "Graphics Gems"
  3710.     Andrew S. Glassner (editor)
  3711.     Academic Press
  3712.     1990
  3713.  
  3714.     "Fundamentals of Interactive Computer Graphics"
  3715.     J. D. Foley and A. Van Dam
  3716.     Addison-Wesley
  3717.     1983
  3718.  
  3719.     "Computer Graphics:  Principles and Practice (2nd Ed.)"     
  3720.     J. D. Foley, A. van Dam, J. F. Hughes
  3721.     Addison-Wesley,
  3722.     1990
  3723.  
  3724.     "Computers, Pattern, Chaos, and Beauty"
  3725.     Clifford Pickover
  3726.     St. Martin's Press
  3727.  
  3728.     "SIGGRAPH Conference Proceedings"
  3729.     Association for Computing Machinery
  3730.     Special Interest Group on Computer Graphics
  3731.  
  3732.     "IEEE Computer Graphics and Applications"
  3733.     The Computer Society
  3734.     10662, Los Vaqueros Circle
  3735.     Los Alamitos, CA 90720
  3736.  
  3737.     "The CRC Handbook of Mathematical Curves and Surfaces"
  3738.     David von Seggern
  3739.     CRC Press
  3740.     1990
  3741.  
  3742.     "The CRC Handbook of Standard Mathematical Tables"
  3743.     CRC Press
  3744.     The Beginning of Time
  3745.  
  3746.  
  3747. 16) Concluding Remarks
  3748.  
  3749. It seems that in any project like this, as soon as you fix some
  3750. bugs, some more appear.  We expect that the new features provided
  3751. in this release will cause some problems somewhere.  Please let us
  3752. know what happens.
  3753.  
  3754.